Trama
OpenAPI JSON

API

Browse the Trama HTTP API for defining workflows, starting executions, inspecting state, and retrying failures. The source contract lives in openapi.json.

Best for integrators HTTP contract OpenAPI-backed
InstallRun the API locally before testing requests. ExamplesSee real workflow definitions and runs. ArchitectureUnderstand what happens after a request is accepted.

Definition formats

The API accepts two execution styles within the same definition model, auto-detected by the presence of nodes. A sequential workflow uses a nodes array with an entrypoint and task nodes linked by next. Add a switch node to branch at runtime, set action.mode: "async" on any task node for callback coordination, add a sleep node to pause the workflow for a configurable duration before continuing, or add a split node (paired with a join) to fan out into independent, concurrently-running branches. Both styles work with stored definitions and inline runs.

Hello world request

curl -X POST http://localhost:8080/workflows/run \
  -H 'Content-Type: application/json' \
  -d '{
    "definition": {
      "name": "inline",
      "version": "v1",
      "failureHandling": {
        "type": "retry",
        "maxAttempts": 1,
        "delayMillis": 200
      },
      "entrypoint": "notify",
      "nodes": [
        {
          "kind": "task",
          "id": "notify",
          "action": {
            "mode": "sync",
            "request": {
              "url": "http://service/run",
              "verb": "POST"
            }
          }
        }
      ]
    },
    "payload": {
      "orderId": "123"
    }
  }'

Endpoints

Filter endpoints:

MethodPathDescription
GET/healthzLiveness probe
GET/readyzReadiness probe
POST/workflows/definitionsCreate definition
GET/workflows/definitionsList definitions
GET/workflows/definitions/{id}Get definition
GET/workflows/definitions/{name}/{version}Get definition by name and version
PUT/workflows/definitions/{id}Insert definition by id
DELETE/workflows/definitions/{id}Delete definition
POST/workflows/definitions/{name}/{version}/runRun stored definition
POST/workflows/runRun inline definition
GET/workflowsList executions (filter by status, name; limit/offset)
GET/workflows/{id}Get execution status
GET/workflows/{id}/stepsStep results (forward, compensation, callback, switch, split/join) in execution order
GET/workflows/{id}/steps/callsOutbound HTTP calls, one per attempt, with rendered request and response
POST/workflows/{id}/retryRetry a FAILED execution
POST/workflows/{id}/wakeWake a sleeping execution early
POST/workflows/{executionId}/node/{nodeId}/callbackDeliver async callback to a waiting node
GET/metricsPrometheus metrics

Retry only accepts executions in FAILED status (anything else returns 409). It re-runs the saga from the first step with its original payload; steps completed before the failure were already compensated. Retrying v2 node-graph executions is not supported yet (422).

Wake returns 202 when it cuts a sleep short, 200 if a wake-up is already under way, and 409 when the execution is not sleeping.

Endpoint Details (from OpenAPI)

Rendered live from openapi.json, including request/response schema references.

Schema Fields (from OpenAPI)

Field-level reference for request and response objects used by this API.

Examples

curl -X POST http://localhost:8080/workflows/run \
  -H 'Content-Type: application/json' \
  -d '{"definition": { ... }, "payload": {"orderId": "123"}}'

Error Model

Validation and operational errors are returned as:

{ "errors": ["message"] }