{ "openapi": "3.0.0", "info": { "title": "Output.ai API", "version": "1.0.0", "description": "API for managing and executing Output.ai workflows" }, "servers": [ { "url": "http://localhost:3001", "description": "Development server" } ], "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "ErrorResponse": { "type": "object", "description": "API error body (WorkflowNotFoundError, UnsupportedWorkflowError, WorkflowExecutionTimedOutError, WorkflowNotCompletedError, CatalogNotAvailableError, or server error)", "properties": { "error": { "type": "string", "description": "Error type name (e.g. WorkflowNotFoundError, UnsupportedWorkflowError, CatalogNotAvailableError)" }, "message": { "type": "string", "description": "Human-readable error message" }, "workflowId": { "type": "string", "description": "Workflow ID when the error is tied to a specific execution (e.g. timeout)", "nullable": true } } }, "ValidationErrorResponse": { "type": "object", "description": "Request body validation failure (Zod)", "properties": { "error": { "type": "string", "enum": [ "ValidationError" ] }, "message": { "type": "string", "example": "Invalid Payload" }, "issues": { "type": "array", "description": "Zod validation issues", "items": { "type": "object" } } } }, "JSONSchema": { "type": "object", "additionalProperties": true, "properties": { "$schema": { "type": "string" }, "type": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONSchema" } }, "items": { "$ref": "#/components/schemas/JSONSchema" }, "required": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "object", "properties": { "type": { "type": "string" } } }, "anyOf": { "type": "array", "items": { "$ref": "#/components/schemas/JSONSchema" } } } }, "Workflow": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the workflow" }, "description": { "type": "string", "description": "The description of the workflow" }, "path": { "type": "string", "description": "Absolute path to the workflow file" }, "inputSchema": { "$ref": "#/components/schemas/JSONSchema" }, "outputSchema": { "$ref": "#/components/schemas/JSONSchema" }, "aliases": { "type": "array", "description": "Alternative names that resolve to this workflow", "items": { "type": "string" } } } }, "TraceInfoV1": { "type": "object", "nullable": true, "description": "Legacy trace information containing nested destinations", "properties": { "destinations": { "type": "object", "description": "Available destinations for trace data", "properties": { "local": { "type": "string", "description": "Absolute path to local trace file, omitted if not saved locally" }, "remote": { "type": "string", "description": "Remote trace location (e.g., S3 URI), omitted if not saved remotely" } } } } }, "TraceInfoV2": { "type": "object", "nullable": true, "description": "Available destinations for trace data", "properties": { "local": { "type": "string", "description": "Absolute path to local trace file, omitted if not saved locally" }, "remote": { "type": "string", "description": "Remote trace location (e.g., S3 URI), omitted if not saved remotely" } } }, "TraceData": { "type": "object", "description": "Trace data containing workflow execution details", "additionalProperties": true, "properties": { "workflowId": { "type": "string", "description": "The workflow execution ID" }, "input": { "type": "object", "description": "The workflow input" }, "output": { "type": "object", "description": "The workflow output" }, "steps": { "type": "array", "description": "The workflow execution steps", "items": { "type": "object" } } } }, "TraceLogRemoteResponse": { "type": "object", "required": [ "source", "runId", "data" ], "properties": { "source": { "type": "string", "enum": [ "remote" ], "description": "Indicates trace was fetched from remote storage" }, "runId": { "type": "string", "description": "The specific run id this trace belongs to" }, "data": { "$ref": "#/components/schemas/TraceData" } } }, "TraceLogLocalResponse": { "type": "object", "required": [ "source", "runId", "localPath" ], "properties": { "source": { "type": "string", "enum": [ "local" ], "description": "Indicates trace is available locally" }, "runId": { "type": "string", "description": "The specific run id this trace belongs to" }, "localPath": { "type": "string", "description": "Absolute path to local trace file" } } }, "WorkflowRunInfo": { "type": "object", "properties": { "workflowId": { "type": "string", "description": "Unique identifier for this run" }, "runId": { "type": "string", "description": "The specific run id for this execution" }, "workflowType": { "type": "string", "description": "Name of the workflow definition" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled", "terminated", "timed_out", "continued_as_new" ], "description": "Current run status" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of run start" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp of completion, or null if still running" } } }, "WorkflowRunsResponse": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunInfo" } }, "count": { "type": "integer", "description": "Total number of runs returned" } } }, "WorkflowStatusResponse": { "type": "object", "properties": { "workflowId": { "type": "string", "description": "The id of workflow" }, "runId": { "type": "string", "description": "The specific run id for this execution" }, "status": { "type": "string", "enum": [ "cancelled", "completed", "continued_as_new", "failed", "running", "terminated", "timed_out", "unspecified" ], "description": "The workflow execution status" }, "startedAt": { "type": "number", "description": "An epoch timestamp representing when the workflow started" }, "completedAt": { "type": "number", "description": "An epoch timestamp representing when the workflow ended" } } }, "WorkflowResultStatus": { "type": "string", "enum": [ "completed", "failed", "cancelled", "terminated", "timed_out", "continued_as_new" ], "description": "The workflow execution status" }, "SerializedWorkflowError": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Structured error details captured from the workflow or activity failure", "properties": { "activityType": { "type": "string", "description": "Failing activity type, omitted when the failure did not originate in an activity" }, "name": { "type": "string", "description": "Original error class name" }, "message": { "type": "string", "description": "Original error message" } } }, "WorkflowResultV1Response": { "type": "object", "deprecated": true, "additionalProperties": false, "description": "Legacy wrapped workflow result", "required": [ "workflowId", "runId", "status", "input", "output", "trace", "error", "errorDetails" ], "properties": { "workflowId": { "type": "string", "description": "The workflow execution id" }, "runId": { "type": "string", "nullable": true, "description": "The specific run id for this execution" }, "status": { "$ref": "#/components/schemas/WorkflowResultStatus" }, "input": { "nullable": true, "description": "The original input passed to the workflow, null if unavailable" }, "output": { "nullable": true, "description": "The result of workflow, null if workflow failed" }, "trace": { "$ref": "#/components/schemas/TraceInfoV1" }, "error": { "type": "string", "nullable": true, "description": "Error message if workflow failed, null otherwise" }, "errorDetails": { "type": "object", "nullable": true, "description": "Structured failure details if the workflow failed, null otherwise", "properties": { "message": { "type": "string", "nullable": true, "description": "Friendly failure message (from the underlying application error)" }, "name": { "type": "string", "nullable": true, "description": "Error name/type (the original error's class)" }, "retryable": { "type": "boolean", "nullable": true, "description": "Whether Temporal flagged the failure retryable; null if unknown" }, "activityId": { "type": "string", "nullable": true, "description": "Failing activity key (\"workflow#step\"); null if no activity failed" }, "cause": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sanitized error cause chain (name/message per level, no stack)" } } } } }, "WorkflowResultV2Response": { "type": "object", "additionalProperties": false, "description": "Current workflow result with direct output and memo-based trace information", "required": [ "v", "workflowId", "runId", "status", "input", "output", "trace", "error" ], "properties": { "v": { "type": "string", "enum": [ "2" ], "description": "Workflow result response version" }, "workflowId": { "type": "string", "description": "The workflow execution id" }, "runId": { "type": "string", "nullable": true, "description": "The specific run id for this execution" }, "status": { "$ref": "#/components/schemas/WorkflowResultStatus" }, "input": { "nullable": true, "description": "The original input passed to the workflow, null if unavailable" }, "output": { "nullable": true, "description": "Direct workflow output, null if no output is available" }, "trace": { "$ref": "#/components/schemas/TraceInfoV2" }, "error": { "allOf": [ { "$ref": "#/components/schemas/SerializedWorkflowError" } ], "nullable": true } } }, "WorkflowResultResponse": { "oneOf": [ { "$ref": "#/components/schemas/WorkflowResultV2Response" }, { "$ref": "#/components/schemas/WorkflowResultV1Response" } ] }, "WorkflowInputResponse": { "type": "object", "required": [ "workflowId", "runId", "input" ], "properties": { "workflowId": { "type": "string", "description": "The workflow execution id" }, "runId": { "type": "string", "description": "The specific run id the input was read from" }, "input": { "description": "The first input argument the workflow was started with, null if unavailable" } } }, "StopWorkflowResponse": { "type": "object", "properties": { "workflowId": { "type": "string" }, "runId": { "type": "string" } } }, "TerminateWorkflowResponse": { "type": "object", "properties": { "terminated": { "type": "boolean" }, "workflowId": { "type": "string" }, "runId": { "type": "string" } } }, "ResetWorkflowRequest": { "type": "object", "required": [ "stepName" ], "properties": { "stepName": { "type": "string", "description": "The name of the step to reset after" }, "reason": { "type": "string", "description": "Optional reason for the reset" } } }, "ResetWorkflowResponse": { "type": "object", "properties": { "workflowId": { "type": "string", "description": "The original workflow ID" }, "runId": { "type": "string", "description": "The run ID of the new execution created by the reset" } } } }, "responses": { "BadRequest": { "description": "Invalid request body, query, or pagination token", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "NotFound": { "description": "Workflow execution, workflow type, or catalog not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RequestTimeout": { "description": "Synchronous execution timed out before workflow completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "FailedDependency": { "description": "Workflow dependency failed (e.g. workflow not in a terminal state, or workflow type is unsupported by the selected catalog)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Workflow run is in a state that conflicts with the requested operation (e.g. operating on an already-terminal run, or resetting to an incomplete step).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Catalog workflow unavailable (worker not running or still starting). Retry-After header may be set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal server error (e.g. Temporal connection failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "security": [], "paths": { "/health": { "get": { "summary": "Health check the API", "responses": { "200": { "description": "It is healthy" } } } }, "/ready": { "get": { "summary": "Check if the API is ready to answer requests", "responses": { "200": { "description": "It is ready" }, "503": { "description": "It is having problems" } } } }, "/workflow/run": { "post": { "summary": "Execute a workflow synchronously", "description": "Executes a workflow and waits for it to complete before returning the result", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflowName", "input" ], "properties": { "workflowName": { "type": "string", "description": "The name of the workflow to execute" }, "input": { "description": "The payload to send to the workflow" }, "workflowId": { "type": "string", "description": "(Optional) The workflowId to use. Must be unique" }, "catalog": { "type": "string", "description": "The catalog (Temporal task queue) to route the execution to. Falls back to the default catalog." }, "taskQueue": { "type": "string", "deprecated": true, "description": "Deprecated alias for `catalog`. If both are sent, `catalog` wins." }, "timeout": { "type": "number", "description": "(Optional) The max time to wait for the execution, defaults to 30s" } } } } } }, "responses": { "200": { "description": "The workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflow/start": { "post": { "summary": "Start a workflow asynchronously", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflowName", "input" ], "properties": { "workflowName": { "type": "string", "description": "The name of the workflow to execute" }, "input": { "description": "The payload to send to the workflow" }, "workflowId": { "type": "string", "description": "(Optional) The workflowId to use. Must be unique" }, "catalog": { "type": "string", "description": "The catalog (Temporal task queue) to route the execution to. Falls back to the default catalog." }, "taskQueue": { "type": "string", "deprecated": true, "description": "Deprecated alias for `catalog`. If both are sent, `catalog` wins." } } } } } }, "responses": { "200": { "description": "The workflow start result", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflowId": { "type": "string", "description": "The id of the started workflow" }, "runId": { "type": "string", "nullable": true, "description": "The first execution's run id for this workflow" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflow/{id}/status": { "get": { "summary": "Get workflow execution status (latest run)", "description": "Returns the status of the latest run for the given workflow. To pin a specific run, use `/workflow/{id}/runs/{rid}/status`.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow to retrieve the status" } ], "responses": { "200": { "description": "The workflow status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStatusResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/status": { "get": { "summary": "Get workflow execution status for a specific run", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow" }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to target" } ], "responses": { "200": { "description": "The workflow status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/stop": { "patch": { "summary": "Stop a specific workflow run", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to stop" } ], "responses": { "200": { "description": "The workflow run was stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/stop": { "patch": { "deprecated": true, "summary": "[Deprecated] Stop the latest workflow run", "description": "Stops the latest run of the given workflow. The returned `runId` reflects the run at describe-time and may differ from the cancelled run if a new execution started concurrently. Deprecated; use `PATCH /workflow/{id}/runs/{rid}/stop` to pin a specific run. Scheduled for removal after 2026-07-16.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workflow run was stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopWorkflowResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/terminate": { "post": { "summary": "Terminate a specific workflow run (force stop)", "description": "Force terminates a workflow run. Unlike stop/cancel, terminate immediately stops the run without allowing cleanup.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to terminate" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for termination" } } } } } }, "responses": { "200": { "description": "The workflow run was terminated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminateWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/terminate": { "post": { "deprecated": true, "summary": "[Deprecated] Terminate the latest workflow run", "description": "Force terminates the latest run. Deprecated; use `POST /workflow/{id}/runs/{rid}/terminate` to target a specific run. Scheduled for removal after 2026-07-16.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "The workflow run was terminated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminateWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/reset": { "post": { "summary": "Reset a specific workflow run to re-run from after a completed step", "description": "Resets a pinned workflow run to the point after a completed step, creating a new run that replays from that point. The current execution is terminated.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow ID to reset" }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to reset" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetWorkflowRequest" } } } }, "responses": { "200": { "description": "The workflow was reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/reset": { "post": { "deprecated": true, "summary": "[Deprecated] Reset the latest workflow run", "description": "Resets the latest run. Deprecated; use `POST /workflow/{id}/runs/{rid}/reset` to target a specific run. Scheduled for removal after 2026-07-16.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetWorkflowRequest" } } } }, "responses": { "200": { "description": "The workflow was reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/result": { "get": { "summary": "Return the result of a workflow (latest run)", "description": "Returns the result of the latest run for the given workflow. To pin a specific run, use `/workflow/{id}/runs/{rid}/result`.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow to retrieve the result" } ], "responses": { "200": { "description": "The workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResultResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/result": { "get": { "summary": "Return the result of a specific workflow run", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to target" } ], "responses": { "200": { "description": "The workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/input": { "get": { "summary": "Return the original input of a workflow (latest run)", "description": "Returns the original input passed to the latest run of the given workflow. Works for workflows in any state, including running. To pin a specific run, use `/workflow/{id}/runs/{rid}/input`.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow to retrieve the input" } ], "responses": { "200": { "description": "The workflow input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowInputResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/input": { "get": { "summary": "Return the original input of a specific workflow run", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow to retrieve the input" }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to target" } ], "responses": { "200": { "description": "The workflow input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowInputResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/trace-log": { "get": { "summary": "Get workflow trace log data (latest run)", "description": "Returns trace data for the latest run of the given workflow. If trace is stored remotely (S3), fetches and returns the data inline. If trace is local only, returns the local path. To pin a specific run, use `/workflow/{id}/runs/{rid}/trace-log`.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of workflow to retrieve trace log" } ], "responses": { "200": { "description": "The trace log response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TraceLogRemoteResponse" }, { "$ref": "#/components/schemas/TraceLogLocalResponse" } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/trace-log": { "get": { "summary": "Get workflow trace log data for a specific run", "description": "Returns trace data for a pinned workflow run. If trace is stored remotely (S3), fetches and returns the data inline. If trace is local only, returns the local path.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to target" } ], "responses": { "200": { "description": "The trace log response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TraceLogRemoteResponse" }, { "$ref": "#/components/schemas/TraceLogLocalResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "424": { "$ref": "#/components/responses/FailedDependency" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/history": { "get": { "summary": "Get paginated workflow execution history", "description": "Returns decoded Temporal history events with optional payload inclusion. First page includes workflow metadata; subsequent pages return events only.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow execution ID" }, { "in": "query", "name": "runId", "schema": { "type": "string" }, "description": "Specific run ID. Required when using pageToken." }, { "in": "query", "name": "pageSize", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Number of events per page" }, { "in": "query", "name": "pageToken", "schema": { "type": "string" }, "description": "Base64 pagination token from previous response" }, { "in": "query", "name": "includePayloads", "schema": { "type": "boolean", "default": false }, "description": "Include decoded input/output payloads in events" }, { "in": "query", "name": "longPollTimeoutMs", "schema": { "type": "integer", "minimum": 1 }, "description": "When set, long-poll for a new event once caught up to the end of history instead of returning immediately, bounding the block by this many milliseconds. Clamped to the server's configured maximum — a caller can shorten the wait but never exceed it. Omit for an immediate response; on timeout returns the same page's cursor unchanged with an empty events array so the caller can retry. Lets a poller keep the block roughly aligned with its own tick interval.\n" } ], "responses": { "200": { "description": "Paginated history events", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "nullable": true, "description": "Workflow metadata (null on subsequent pages)" }, "events": { "type": "array", "items": { "type": "object" } }, "runId": { "type": "string", "description": "Resolved run ID. Echo this value as the runId query parameter when fetching subsequent pages." }, "nextPageToken": { "type": "string", "nullable": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/history": { "get": { "summary": "Get paginated workflow execution history for a specific run", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow execution ID" }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run id to target" }, { "in": "query", "name": "pageSize", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Number of events per page" }, { "in": "query", "name": "pageToken", "schema": { "type": "string" }, "description": "Base64 pagination token from previous response" }, { "in": "query", "name": "includePayloads", "schema": { "type": "boolean", "default": false }, "description": "Include decoded input/output payloads in events" }, { "in": "query", "name": "longPollTimeoutMs", "schema": { "type": "integer", "minimum": 1 }, "description": "When set, long-poll for a new event once caught up to the end of history instead of returning immediately, bounding the block by this many milliseconds. Clamped to the server's configured maximum — a caller can shorten the wait but never exceed it. Omit for an immediate response; on timeout returns the same page's cursor unchanged with an empty events array so the caller can retry. Lets a poller keep the block roughly aligned with its own tick interval.\n" } ], "responses": { "200": { "description": "Paginated history events", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "nullable": true, "description": "Workflow metadata (null on subsequent pages)" }, "events": { "type": "array", "items": { "type": "object" } }, "runId": { "type": "string", "description": "The pinned run ID" }, "nextPageToken": { "type": "string", "nullable": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/history/stream": { "get": { "summary": "Stream workflow history events via Server-Sent Events", "description": "Opens a persistent SSE connection that delivers Temporal workflow history events in real time. Emits named events: `workflow` (metadata, once), `history` (event batches), `done` (terminal state), `server_error` (post-flush errors). The `done` event carries `{ reason, newRunId? }` where `reason` is the terminal Temporal event type (`WORKFLOW_EXECUTION_COMPLETED`, `WORKFLOW_EXECUTION_FAILED`, `WORKFLOW_EXECUTION_TIMED_OUT`, `WORKFLOW_EXECUTION_CANCELED`, `WORKFLOW_EXECUTION_TERMINATED`, `WORKFLOW_EXECUTION_CONTINUED_AS_NEW`) and `newRunId` is present only when the terminal event chains a follow-on run. `server_error` carries `{ error, message, workflowId, runId }`. Errors before the stream opens are returned as JSON HTTP responses (400/404); once open, failures arrive as a `server_error` event. Supports reconnect via `Last-Event-ID` header or `lastEventId` query param.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow execution ID" }, { "in": "query", "name": "includePayloads", "schema": { "type": "boolean", "default": false }, "description": "Include decoded input/output payloads in events" }, { "in": "query", "name": "lastEventId", "schema": { "type": "integer" }, "description": "Resume from this event ID (alternative to Last-Event-ID header)" } ], "responses": { "200": { "description": "SSE stream of workflow history events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/runs/{rid}/history/stream": { "get": { "summary": "Stream pinned-run workflow history events via Server-Sent Events", "description": "Same as /workflow/{id}/history/stream but targets a specific run ID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow execution ID" }, { "in": "path", "name": "rid", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The specific run ID to target" }, { "in": "query", "name": "includePayloads", "schema": { "type": "boolean", "default": false }, "description": "Include decoded input/output payloads in events" }, { "in": "query", "name": "lastEventId", "schema": { "type": "integer" }, "description": "Resume from this event ID (alternative to Last-Event-ID header)" } ], "responses": { "200": { "description": "SSE stream of workflow history events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/catalog/{id}": { "get": { "summary": "Get a specific workflow catalog by ID", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The id of the catalog" } ], "responses": { "200": { "description": "The catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "description": "Each workflow available in this catalog", "items": { "$ref": "#/components/schemas/Workflow" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/catalog": { "get": { "summary": "Get the default workflow catalog", "responses": { "200": { "description": "The catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "description": "Each workflow available in this catalog", "items": { "$ref": "#/components/schemas/Workflow" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/runs": { "get": { "summary": "List workflow runs", "description": "Returns a list of workflow runs with optional filtering by workflow type", "parameters": [ { "in": "query", "name": "workflowType", "schema": { "type": "string" }, "description": "Filter by workflow type/name" }, { "in": "query", "name": "catalog", "schema": { "type": "string" }, "description": "Filter by catalog ID (scopes runs to a single worker's catalog/session)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of runs to return" } ], "responses": { "200": { "description": "List of workflow runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/feedback": { "post": { "summary": "Send feedback to a workflow", "description": "Always targets the latest run; `runId` cannot be pinned for Temporal signal operations.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow id" } ], "requestBody": { "description": "Body must contain payload; payload is sent to Temporal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "description": "The payload sent to the workflow", "type": "object" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/signal/{signal}": { "post": { "summary": "Send a signal to an workflow", "description": "Always targets the latest run; `runId` cannot be pinned for Temporal signal operations.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow id" }, { "in": "path", "name": "signal", "required": true, "schema": { "type": "string" }, "description": "The signal name" } ], "requestBody": { "description": "Body must contain payload; payload is sent to Temporal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "description": "The payload sent to the signal operation", "type": "object" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/query/{query}": { "post": { "summary": "Send a query to an workflow", "description": "Always targets the latest run; `runId` cannot be pinned for Temporal query operations.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow id" }, { "in": "path", "name": "query", "required": true, "schema": { "type": "string" }, "description": "The query name" } ], "requestBody": { "description": "Body must contain payload; payload is sent to Temporal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "description": "The payload sent to the query operation", "type": "object" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflow/{id}/update/{update}": { "post": { "summary": "Execute an update on an workflow", "description": "Always targets the latest run; `runId` cannot be pinned for Temporal update operations.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The workflow id" }, { "in": "path", "name": "update", "required": true, "schema": { "type": "string" }, "description": "The update name" } ], "requestBody": { "description": "Body must contain payload; payload is sent to Temporal", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "description": "The payload sent to the update operation", "type": "object" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/heartbeat": { "post": { "summary": "A dummy post endpoint for test only", "responses": { "204": { "description": "Success" } } } } }, "tags": [] }