YAML workflows

These endpoints manage YAML workflow definitions: the compiled deterministic pipelines generated from successful MCP triage executions. Each namespace (app_id) acts as a process server, and each workflow is a tool within that server.

Every endpoint requires authentication.

Auth: Creating, updating, regenerating, deleting, deploying, activating, archiving and restoring workflows, and setting or clearing a cron schedule (PUT/DELETE /api/yaml-workflows/:id/cron), require builder access (superadmin or the engineer role). Reads and invoke are open to any authenticated caller.

An execute_as on invoke or on a cron schedule follows the act-as rule: 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.

List workflows

GET /api/yaml-workflows

Returns YAML workflows matching the filters, with a total count.

Query parameters

Parameter	Type	Description
status	string	Filter by status: draft, deployed, active, archived
graph_topic	string	Filter by graph topic (tool name)
app_id	string	Filter by namespace or server (exact match)
search	string	Search name, graph topic, description or app ID (case-insensitive)
source_workflow_id	string	Filter by source execution workflow ID
limit	integer	Max results (default: 50)
offset	integer	Pagination offset (default: 0)

Example request

curl "https://lt.acme.dev/api/yaml-workflows?status=active&app_id=lt-yaml" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "workflows": [
    {
      "id": "a1b2c3d4-...",
      "name": "rotate-and-verify",
      "description": "Rotate document, extract info, validate",
      "app_id": "lt-yaml",
      "app_version": "3",
      "source_workflow_id": "mcp-triage-abc123",
      "source_workflow_type": "mcpTriage",
      "yaml_content": "app:\n  id: lt-yaml\n  version: \"3\"\n...",
      "graph_topic": "rotate_and_verify",
      "input_schema": { "type": "object", "properties": { "image_ref": { "type": "string" } } },
      "output_schema": {},
      "activity_manifest": [
        {
          "activity_id": "a0",
          "title": "Rotate Page",
          "type": "worker",
          "topic": "rotate_and_verify/a0",
          "tool_source": "mcp",
          "mcp_server_id": "srv-1",
          "mcp_tool_name": "rotate_image",
          "input_mappings": {},
          "output_fields": ["rotated_url"]
        }
      ],
      "status": "active",
      "deployed_at": "2025-01-10T00:00:00Z",
      "activated_at": "2025-01-10T00:01:00Z",
      "metadata": null,
      "created_at": "2025-01-09T00:00:00Z",
      "updated_at": "2025-01-10T00:01:00Z"
    }
  ],
  "total": 1
}

Create a workflow (from execution)

POST /api/yaml-workflows

Generates a YAML workflow from a completed MCP triage execution.

Auth: Requires builder access.

Request body

Field	Type	Required	Description
workflow_id	string	Yes	Source execution workflow ID
task_queue	string	Yes	Task queue of the source execution
workflow_name	string	Yes	Source workflow type name
name	string	Yes	Name for the new workflow
description	string	No	Human-readable description
app_id	string	No	Namespace or app ID (default: auto-generated)
subscribes	string	No	Topic subscription
tags	string[]	No	Tags for workflow discovery
compilation_feedback	string	No	Additional instructions for the compilation pipeline

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "mcp-triage-abc123",
    "task_queue": "long-tail",
    "workflow_name": "mcpTriage",
    "name": "rotate-and-verify",
    "description": "Rotate document, extract info, validate",
    "app_id": "lt-yaml"
  }'

Response 201

The created workflow record.

Response 400: missing required fields.

Response 409: the workflow name already exists.

Response 422: the source execution exhausted its tool rounds (incomplete trace).

Get a workflow

GET /api/yaml-workflows/:id

Returns one YAML workflow record.

Path parameters

Parameter	Description
id	Workflow UUID

Example request

curl https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-... \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

The workflow record (same shape as a List workflows element).

Response 404: workflow not found.

Update a workflow

PUT /api/yaml-workflows/:id

Applies a partial update to a workflow.

Auth: Requires builder access.

Request body

Partial update of any of yaml_content, name, description.

Example request

curl -X PUT https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-... \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Rotate, extract and validate a document" }'

Response 200

The updated workflow record.

Response 404: workflow not found.

Delete a workflow

DELETE /api/yaml-workflows/:id

Deletes a workflow. Allowed only for draft or archived workflows.

Auth: Requires builder access.

Example request

curl -X DELETE https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-... \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "deleted": true }

Response 400: active or deployed workflows cannot be deleted.

Response 404: workflow not found.

Deploy a workflow

POST /api/yaml-workflows/:id/deploy

Deploys all YAML workflows sharing this workflow’s app_id as a merged version. It bumps the version, marks all non-archived siblings as active, and registers HotMesh workers for the deployed workflows.

Auth: Requires builder access.

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../deploy \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

The updated workflow record (with the new version).

Response 404: workflow not found.

Activate a workflow

POST /api/yaml-workflows/:id/activate

Activates the deployed version and registers workers for all workflows in the same app_id. Requires status deployed or active.

Auth: Requires builder access.

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../activate \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

The updated workflow record.

Response 400: the workflow must be deployed first.

Response 404: workflow not found.

Invoke a workflow

POST /api/yaml-workflows/:id/invoke

Invokes an active YAML workflow with parameters. The server sets the workflow’s _scope identity context, and a _scope key in data is ignored.

Request body

Field	Type	Required	Description
data	object	No	Input data matching the workflow’s input_schema
sync	boolean	No	Wait for the result (default: false)
timeout	integer	No	Timeout in ms for sync invocations (default: 120000)
execute_as	string	No	Account id or external_id to run as. Must satisfy the act-as rule.

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../invoke \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "image_ref": "scans/order-1001.png" }, "sync": true, "timeout": 60000 }'

Response 200 (async)

{ "job_id": "hmsh:lt-yaml:j:abc123..." }

Response 200 (sync)

{
  "job_id": "hmsh:lt-yaml:j:abc123...",
  "result": {
    "metadata": { "jid": "abc123", "tpc": "rotate_and_verify" },
    "data": { "rotated_url": "https://...", "verified": true }
  }
}

Response 400: the workflow must be active to invoke.

Response 404: workflow not found.

Regenerate a workflow

POST /api/yaml-workflows/:id/regenerate

Regenerates the YAML from the original source execution. Allowed for draft, deployed and active workflows.

Auth: Requires builder access.

Request body

Field	Type	Required	Description
task_queue	string	No	Override task queue (default: from source)
compilation_feedback	string	No	Additional instructions for the regeneration

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../regenerate \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "compilation_feedback": "Validate the rotation before extracting fields." }'

Response 200

The updated workflow record.

Response 400: archived workflows cannot be regenerated.

Response 404: workflow not found.

Archive a workflow

POST /api/yaml-workflows/:id/archive

Stops accepting invocations. If the workflow is active, its engine stops.

Auth: Requires builder access.

Example request

curl -X POST https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../archive \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

The updated workflow record with status archived.

Response 404: workflow not found.

List app IDs

GET /api/yaml-workflows/app-ids

Returns the distinct app_id values of non-archived workflows.

Example request

curl https://lt.acme.dev/api/yaml-workflows/app-ids \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "app_ids": ["lt-yaml", "my-custom-app"]
}

Get version history

GET /api/yaml-workflows/:id/versions

Returns the version history for a YAML workflow.

Query parameters

Parameter	Type	Description
limit	integer	Max results (default: 20)
offset	integer	Pagination offset (default: 0)

Example request

curl "https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../versions?limit=10" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

Version history records.

Response 404: workflow not found.

Get version snapshot

GET /api/yaml-workflows/:id/versions/:version

Returns a single version snapshot with YAML content, schemas and activity manifest.

Path parameters

Parameter	Description
id	Workflow UUID
version	Version number (positive integer)

Example request

curl https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../versions/3 \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

The version snapshot object.

Response 400

{ "error": "Invalid version number" }

Response 404

{ "error": "Version 3 not found" }

Get raw YAML

GET /api/yaml-workflows/:id/yaml

Returns the raw YAML content as text/yaml. The optional version query parameter returns the YAML for a specific version.

Query parameters

Parameter	Type	Description
version	integer	Return YAML for this version instead of the current one

Example request

curl "https://lt.acme.dev/api/yaml-workflows/a1b2c3d4-.../yaml?version=3" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

YAML content (Content-Type: text/yaml).

Response 404: workflow or version not found.