Pipelines

Query and manage pipeline execution runs. Runs live in HotMesh’s {namespace}.jobs table, one schema per namespace. The same routes also answer under /api/mcp-runs.

All endpoints require authentication.

List runs

GET /api/pipelines

Returns runs for one namespace, newest first, with optional filters.

Query parameters

Parameter	Type	Description
app_id	string	Required. Namespace to query (for example longtail, lt-yaml).
entity	string	Filter by tool or entity name (for example rotate_and_verify).
search	string	Search by workflow ID substring (case-insensitive).
status	string	Filter by status: running, completed, failed.
limit	integer	Max results (default 20, max 100).
offset	integer	Pagination offset (default 0).

Example request

curl -s "https://lt.acme.dev/api/pipelines?app_id=lt-yaml&status=completed&limit=20" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "jobs": [
    {
      "workflow_id": "abc123...",
      "entity": "rotate_and_verify",
      "status": "completed",
      "is_live": false,
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:05Z"
    }
  ],
  "total": 1
}

Response 400: app_id is missing.

List entities (tools)

GET /api/pipelines/entities

Returns distinct entity names from job runs, plus the graph_topic values of active and deployed YAML workflows in the namespace. Names are sorted alphabetically and exclude null or empty values.

Query parameters

Parameter	Type	Description
app_id	string	Required. Namespace to query.

Example request

curl -s "https://lt.acme.dev/api/pipelines/entities?app_id=lt-yaml" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "entities": ["extract_info", "rotate_and_verify"]
}

Response 400: app_id is missing.

Get execution detail

GET /api/pipelines/:jobId/execution

Returns full execution detail for one run: inflated activity events, trace ID and a summary.

Path parameters

Parameter	Description
jobId	The run’s workflow ID.

Query parameters

Parameter	Type	Description
app_id	string	Required. Namespace to query.

Example request

curl -s "https://lt.acme.dev/api/pipelines/abc123/execution?app_id=lt-yaml" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "workflow_id": "abc123...",
  "workflow_type": "rotate_and_verify",
  "workflow_name": "rotate_and_verify",
  "task_queue": "lt-yaml",
  "status": "completed",
  "start_time": "2025-01-15T10:00:00.000Z",
  "close_time": "2025-01-15T10:00:05.230Z",
  "duration_ms": 5230,
  "trace_id": "a5fb792464c1d6c7e692824f0ceb011d",
  "result": { "rotated_url": "https://...", "verified": true },
  "events": [...],
  "summary": {
    "total_events": 5,
    "activities": { "total": 2, "completed": 2, "failed": 0, "system": 1, "user": 1 },
    "child_workflows": { "total": 0, "completed": 0, "failed": 0 },
    "timers": 0,
    "signals": 0
  }
}

Response 400: app_id is missing.

Response 404: Job not found.

Interrupt a running pipeline

POST /api/pipelines/:jobId/interrupt

Terminates a running pipeline job with HotMesh.interrupt(). The job is marked interrupted and its state is expired.

Auth: Requires builder access (superadmin or the engineer role).

Path parameters

Parameter	Description
jobId	The run’s workflow ID.

Request body

Field	Type	Description
topic	string	Required. Workflow entity or topic name.
app_id	string	Required. HotMesh namespace.

Example request

curl -s https://lt.acme.dev/api/pipelines/abc123/interrupt \
  -X POST \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic": "rotate_and_verify", "app_id": "longtail"}'

Response 200

{
  "interrupted": true,
  "jobId": "abc123..."
}

Response 400: topic or app_id is missing.