Overview

How your application communicates with Output workflows over HTTP

Your application talks to Output through a REST API. When you deploy Output, the API server exposes HTTP endpoints for running workflows, checking their status, and retrieving results. Your backend sends a request, Output orchestrates the workflow, and you get structured results back.

During development, the API server starts automatically on port 3001 when you run output dev.

Two Ways to Run Workflows

Choose based on how long your workflow takes and how your application handles responses.

Run and Wait (Synchronous)

POST /workflow/run blocks until the workflow completes and returns the result in the response body. Use this when workflows complete quickly (seconds) and your client can wait.

curl -X POST http://localhost:3001/workflow/run \
  -H "Content-Type: application/json" \
  -d '{"workflowName": "summarize_url", "input": {"url": "https://example.com/article"}}'

Start and Poll (Asynchronous)

POST /workflow/start returns the workflow ID immediately. Poll for status and retrieve the result when ready. Use this for longer workflows — minutes or more — where blocking a request isn’t practical.

# Start the workflow
curl -X POST http://localhost:3001/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"workflowName": "company_research", "input": {"domain": "example.com"}}'

# Check status
curl http://localhost:3001/workflow/<workflow-id>/status

# Get result when completed
curl http://localhost:3001/workflow/<workflow-id>/result

Workflow Result Payload

POST /workflow/run and GET /workflow/:id/result return the same structured workflow result:

{
  "workflowId": "lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "runId": "b5c6d7e8-9012-3456-7890-abcdef123456",
  "status": "completed",
  "input": { "companyDomain": "acme.com" },
  "output": {
    "company": "Acme Corp",
    "summary": "Enterprise software company focused on..."
  },
  "trace": { "destinations": {} },
  "attributes": [
    {
      "type": "llm:usage",
      "modelId": "anthropic/claude-3-5-sonnet",
      "total": 0.0084,
      "tokensUsed": 1200,
      "usage": [
        { "type": "input", "ppm": 3, "amount": 800, "total": 0.0024 },
        { "type": "output", "ppm": 15, "amount": 400, "total": 0.006 }
      ]
    }
  ],
  "aggregations": {
    "cost": { "total": 0.0084 },
    "tokens": { "total": 1200, "input": 800, "output": 400 },
    "httpRequests": { "total": 0 }
  },
  "error": null
}

Field	Description
workflowId	Workflow execution ID.
runId	Specific Temporal run ID.
status	Current or final execution status.
input	Original workflow input.
output	Value returned by the workflow on success, or null on failure.
trace	Trace metadata for the run, or null when unavailable.
attributes	Durable workflow attributes collected during execution, such as LLM usage and HTTP cost/count attributes.
aggregations	Convenience totals derived from attributes, including cost.total, tokens.total, and httpRequests.total.
error	Error message on failure, otherwise null.

attributes are the primary data source for usage and cost details. Use aggregations when you only need high-level totals for billing, reporting, or dashboards.

When a workflow fails after collecting attributes, the result still includes the available trace, attributes, and aggregations fields alongside the error message.

Interacting with Running Workflows

Output supports sending data to running workflows and reading their state via signals, queries, and updates. The workflow must define handlers for these — see External Integration for how to set them up.

Method	What it does	Use case
Signal POST /workflow/:id/signal/:name	Push data into a workflow	Human approval, external events
Query POST /workflow/:id/query/:name	Read workflow state without changing it	Progress checks, status dashboards
Update POST /workflow/:id/update/:name	Change state and get confirmation	Configuration changes, priority updates

Stopping Workflows

• PATCH /workflow/:id/stop — Graceful stop. Allows cleanup handlers to run.
• POST /workflow/:id/terminate — Force terminate. Immediate, no cleanup.

Workflow Discovery

GET /workflow/catalog returns all available workflows with their input and output schemas. Use this to build dynamic UIs or validate inputs before submitting.

Debugging

GET /workflow/:id/trace-log returns the full execution trace for a completed workflow. See Tracing for the trace format.

For remote traces, the API server needs AWS credentials (OUTPUT_AWS_ACCESS_KEY_ID, OUTPUT_AWS_SECRET_ACCESS_KEY, OUTPUT_AWS_REGION).

What’s Next

Configuration

Configuration. Base URL, ports, and environment variables for the API server.

Authentication

Authentication. How auth works in development vs production.

Error Responses

Error Responses. Error codes, response format, and how to handle failures.