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, or add a sleep node to pause the workflow for a configurable duration before continuing. Both styles work with stored definitions and inline runs.

Hello world request

curl -X POST http://localhost:8080/sagas/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/sagas/definitionsCreate definition
GET/sagas/definitionsList definitions
GET/sagas/definitions/{id}Get definition
PUT/sagas/definitions/{id}Insert definition by id
DELETE/sagas/definitions/{id}Delete definition
POST/sagas/definitions/{name}/{version}/runRun stored definition
POST/sagas/runRun inline definition
GET/sagas/{id}Get execution status
POST/sagas/{id}/retryRetry failed execution
POST/sagas/{id}/wakeWake a sleeping execution early
POST/sagas/{id}/node/{nodeId}/callbackDeliver async callback to a waiting node
GET/metricsPrometheus metrics

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/sagas/run \
  -H 'Content-Type: application/json' \
  -d '{"definition": { ... }, "payload": {"orderId": "123"}}'

Error Model

Validation and operational errors are returned as:

{ "errors": ["message"] }