lt.workflows

lt.workflows starts durable workflows, reads their status, envelopes and results, terminates runs, and manages workflow configuration. See Workflows.

invoke

const result = await lt.workflows.invoke({
  type: 'reviewContent',
  data: { url: 'https://example.com/page' },
  metadata: { source: 'dashboard' },
});

Start a workflow. Resolves the task queue, enforces auth and role constraints, builds the envelope with identity context, and starts the run. Any durable WorkflowOptions field (workflowId, expire, entity, namespace, search, signalIn, pending and so on) passes through options.

Parameters

Field	Type	Required	Description
`type`	`string`	Yes	Workflow function name
`data`	`Record<string, any>`	No	Envelope data
`metadata`	`Record<string, any>`	No	Envelope metadata
`execute_as`	`string`	No	Account id or `external_id` to run as (see the act-as rule below)
`options`	`Record<string, any>`	No	Passed through to `WorkflowOptions`

Returns: LTApiResult<{ workflowId, message }> with status 202.

Auth: Required. When the workflow’s invocation_roles is set, the caller must hold one of them (read from the caller’s current grants). Empty invocation_roles admits any authenticated caller. A superadmin grant, or the admin role held with admin type, invokes any workflow. capabilityInvoke requires a superadmin grant. For execute_as, a superadmin may act as anyone, and a caller holding an admin-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type; otherwise 403.

getStatus

const result = await lt.workflows.getStatus({ workflowId: 'wf_abc' });
// after lt.workflows.terminate({ workflowId: 'wf_abc' }):
// result.data → { workflowId: 'wf_abc', status: -999999999, state: 'failed', terminated: true }

Get a workflow’s execution status.

Parameters

Field	Type	Required	Description
`workflowId`	`string`	Yes	Workflow ID

Returns: LTApiResult<{ workflowId, status, state, terminated, error? }>. 404 if not found.

Field	Meaning
`status`	HotMesh job status: above 0 running, 0 closed, below 0 terminated
`state`	`running`, `completed` or `failed`. A run that closed with an error is `failed` at status 0; a terminated run is `failed`
`terminated`	`true` when an interrupt ended the run
`error`	The failure message, when HotMesh still holds it

Auth: Not required.

getEnvelopes

const result = await lt.workflows.getEnvelopes({ workflowId: 'reviewContent-a1b2c3d4' });
// result.data → { workflow_id, status, input, output, error? }

Read a workflow’s input and output envelopes. Two narrow lookups that return at once. While the run is in flight, output is null with status: 'running'. A failed run answers status: 'failed' with the workflow’s error.

Parameters

Field	Type	Required	Description
`workflowId`	`string`	Yes	Workflow ID

Returns: LTApiResult<{ workflow_id, status: 'running' | 'completed' | 'failed', terminated?, input, output, error? }>. terminated: true when an interrupt ended the run. 404 when the workflow is unknown or expired.

Auth: Not required.

getResult

const result = await lt.workflows.getResult({ workflowId: 'wf_abc' });

Get a workflow’s result. Returns at once: 202 while the run is in flight, and a failed or terminated run answers with its error.

Parameters

Field	Type	Required	Description
`workflowId`	`string`	Yes	Workflow ID

Returns: one of:

LTApiResult<{ workflowId, state: 'completed', result }> (200)
LTApiResult<{ workflowId, state: 'failed', terminated, error?, result: null }> (200)
LTApiResult<{ workflowId, status: 'running' }> (202)

404 if not found.

Auth: Not required.

terminate

const result = await lt.workflows.terminate({ workflowId: 'wf_abc' });

Terminate a running workflow. Terminate acts on the named run; terminate a child run by its own id.

Parameters

Field	Type	Required	Description
`workflowId`	`string`	Yes	Workflow ID

Returns: LTApiResult<{ terminated: true, workflowId }>. 404 if not found.

Auth: Not required.

export

const result = await lt.workflows.export({ workflowId: 'wf_abc' });

Export a workflow’s full state, including activity results, signals and metadata.

Parameters

Field	Type	Required	Description
`workflowId`	`string`	Yes	Workflow ID

Returns: LTApiResult<ExportedState>. 404 if not found.

Auth: Not required.

listWorkers

const result = await lt.workflows.listWorkers({ include_system: false });

List active workflow workers with their registration status.

Parameters

Field	Type	Required	Description
`include_system`	`boolean`	No	Include system workflows (default `false`)

Returns: LTApiResult<{ workers: [{ name, task_queue, registered, system }] }>

Auth: Not required.

listDiscovered

const result = await lt.workflows.listDiscovered({ include_system: false });

List every known workflow type, merged from three sources: active in-memory workers, historical entities in the durable jobs table, and registered workflow configs.

Parameters

Field	Type	Required	Description
`include_system`	`boolean`	No	Include system workflows (default `false`)

Returns: LTApiResult<{ workflows: [{ workflow_type, task_queue, tier, registered, active, invocable, system, description, roles, invocation_roles, execute_as }] }>. tier is certified, registered or durable.

Auth: Not required.

getCronStatus

const result = await lt.workflows.getCronStatus();

List every cron-scheduled workflow and whether its schedule is active.

Parameters: none.

Returns: LTApiResult<{ schedules: [{ workflow_type, cron_schedule, description, task_queue, invocable, active, envelope_schema }] }>

Auth: Not required.

listConfigs

const result = await lt.workflows.listConfigs();

List every registered workflow configuration.

Parameters: none.

Returns: LTApiResult<{ workflows: LTWorkflowConfig[] }>

Auth: Not required.

getConfig

const result = await lt.workflows.getConfig({ type: 'reviewContent' });

Get one workflow configuration by type.

Parameters

Field	Type	Required	Description
`type`	`string`	Yes	Workflow type

Returns: LTApiResult<LTWorkflowConfig>. 404 if not found.

Auth: Not required.

upsertConfig

const result = await lt.workflows.upsertConfig({
  type: 'reviewContent',
  invocable: true,
  task_queue: 'content-review',
  default_role: 'reviewer',
  description: 'Review flagged content',
});

Create or replace a workflow configuration. Invalidates the config cache and restarts the cron schedule when one is set. Idempotent.

Parameters

Field	Type	Required	Description
`type`	`string`	Yes	Workflow type
`invocable`	`boolean`	No	Whether the workflow can be started through the API
`certified`	`boolean`	No	Explicit interceptor treatment. When omitted, derived from whether `roles` or `consumes` is set
`task_queue`	`string \| null`	No	Task queue
`default_role`	`string`	No	Default escalation role
`description`	`string \| null`	No	Description
`execute_as`	`string \| null`	No	Service account for proxy invocation
`roles`	`string[]`	No	Who resolves escalations the interceptor raises
`invocation_roles`	`string[]`	No	Roles that can invoke the workflow
`consumes`	`string[]`	No	Workflow types whose data this workflow consumes
`tool_tags`	`string[]`	No	MCP tool tags for discovery
`envelope_schema`	`any`	No	JSON Schema for `envelope.data`
`resolver_schema`	`any`	No	Deprecated legacy fallback. The escalation form belongs to the target role as a versioned `form_schema`
`cron_schedule`	`string \| null`	No	Cron expression for scheduled runs

Returns: LTApiResult<LTWorkflowConfig>

Auth: Not required.

deleteConfig

const result = await lt.workflows.deleteConfig({ type: 'reviewContent' });

Delete a workflow configuration and invalidate the cache. Active workers keep running.

Parameters

Field	Type	Required	Description
`type`	`string`	Yes	Workflow type

Returns: LTApiResult<{ deleted: true, workflow_type }>. 404 if not found.

Auth: Not required.