Getting Started

Base URL, first API call, response format, error handling, and pagination

Base URL

All API requests are made to:

https://dev.steelengine.com

The SteelEngine app itself runs at {{APP_URL}}. Use that address to open workflows in the editor, and {{API_URL}} for API calls.

Quick Start

Get your API key

Go to the SteelEngine platform and navigate to Settings, then go to API Keys and click Create. See Authentication for details on key types.

Find your workflow ID

Open a workflow in the SteelEngine editor. The workflow ID is the last UUID in the URL:

https://dev.steelengine.com/{orgSlug}/{workspaceSlug}/w/{workflowId}

The first segment after the host is your organization's slug, the second is your workspace's slug, and {workflowId} is the workflow's UUID. See Organizations and Workspaces for the slug rules.

You can also use the List Workflows endpoint to get all workflow IDs in a workspace.

Deploy your workflow

A workflow must be deployed before it can be executed via the API. Click the Deploy button in the editor toolbar, or call Deploy Workflow with a key whose owner is a workspace admin:

curl -X POST https://dev.steelengine.com/api/workflows/{workflowId}/deploy \
  -H "X-API-Key: YOUR_API_KEY"

To roll back, list versions with List Deployments and activate one with Update Deployment Version. The API manages deployments only. Edit the workflow itself in the editor.

Make your first request

The top-level fields of the request body are the workflow's input. Name them after the input fields defined on the workflow's Start block:

curl -X POST https://dev.steelengine.com/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "Hello"}'

You can also wrap the fields in a top-level input object. {"input": {"message": "Hello"}} reaches the workflow the same way. Send a plain string, number, or array as input. The fields stream, selectedOutputs, useDraftState, includeFileBase64, base64MaxBytes, and stopAfterBlockId are execution controls. SteelEngine never passes them to the workflow. See Execute Workflow for what each one does.

Sync vs Async Execution

By default, workflow executions are synchronous — the API blocks until the workflow completes and returns the result directly.

For long-running workflows, use asynchronous execution by sending the X-Execution-Mode: async header:

curl -X POST https://dev.steelengine.com/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Execution-Mode: async" \
  -d '{"message": "Hello"}'

This returns immediately (HTTP 202) with a jobId:

{
  "success": true,
  "async": true,
  "jobId": "exec_def456",
  "executionId": "exec_def456",
  "message": "Workflow execution queued",
  "statusUrl": "https://dev.steelengine.com/api/jobs/exec_def456"
}

The jobId is the execution ID. Poll the Get Job Status endpoint until the status is completed, failed, or cancelled:

curl https://dev.steelengine.com/api/jobs/{jobId} \
  -H "X-API-Key: YOUR_API_KEY"

Job status transitions follow: pending → processing → completed, failed, or cancelled. A run that is waiting for human input reports paused and is not finished. The output field is present once the run has a result.

On SteelEngine Cloud a run's execution record expires 7 days after it finishes. After that the endpoint answers from run history: the same status and times, metadata.source: "run-history", and the run-history copy of the output, which is size-capped and has secrets removed. Once run history is deleted, 30 days after the run finishes, the endpoint returns 404.

To skip polling, send X-Callback-Url and X-Callback-Secret with the async request. SteelEngine then POSTs the same Get Job Status body, signed with your secret, to that HTTPS URL when the run completes, fails, or is cancelled. See Completion Callbacks for the header rules, signature verification, and retries.

Async requests cannot carry the execution controls useDraftState, selectedOutputs, stopAfterBlockId, includeFileBase64, or base64MaxBytes. If they are present, the API returns 400.

A synchronous request can also return HTTP 202. This happens when the run was admitted but its result did not arrive in time. The body is then a pending receipt: {"success": true, "pending": true, "executionId": "...", "statusUrl": "..."}. The run is still going. Poll statusUrl. Sending the request again would start a second run.

You can also receive block outputs as they are produced. Set stream: true in the body. List the outputs in selectedOutputs as blockName.field, for example agent1.content. Send the X-SteelEngine-Stream-Version: 2 header. The response is a Server-Sent Events stream. See the TypeScript SDK for the frame format and a reader.

Workflow Deadlines and Request Timeouts

The workflow's Execution timeout sets a hard elapsed-time limit for new runs, including async runs, waits, and approval pauses. A client HTTP timeout or a 202 pending response does not extend or reset that deadline. Poll the existing run's statusUrl to learn its outcome.

Read data.timeoutSeconds with Get Workflow Definition: an integer is the configured limit in seconds, and null means platform defaults. Configure it through the workflow menu. The builder's metadata update endpoint requires session or trusted internal authentication and does not accept API keys.

Paused Runs

A run that reaches a Human in the Loop block stops and waits for a decision. Its status is paused, and its output carries _resume links. To find and continue paused runs:

  • List Paused Executions returns a workflow's paused runs. Send status=paused,partially_resumed to get the runs that are still waiting.
  • Get Paused Execution returns one run with each pause point, its resume form, and its contextId.
  • Resume Execution submits the decision for one pause point. It needs write access to the workflow. Like execute, it can answer synchronously, stream, or return 202 with a statusUrl when you send X-Execution-Mode: async.

Pause records use resumed when their current pause is resolved in per-block execution, or fully_resumed in legacy execution. Use status=resumed,fully_resumed to find resolved pause records across both runtimes. A per-block record can remain paused after a partial resume. These statuses describe the pause record; they do not confirm that the workflow finished successfully.

A successful synchronous resume returns status: "success" or status: "completed", depending on the runtime. Handle both as successful completion. A result can also be failed, cancelled, paused if more human input is needed, or queued if another resume is already running. For an asynchronous response, poll its statusUrl using Get Job Status for the final workflow outcome.

curl -X POST https://dev.steelengine.com/api/resume/{workflowId}/{executionId}/{contextId} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {"approved": true}}'

Response Format

A successful synchronous execution returns the execution result, marked with the X-SteelEngine-Response-Type: execution header:

{
  "success": true,
  "executionId": "exec_def456",
  "output": {
    "result": "Hello, world!"
  },
  "metadata": {
    "startTime": "2025-01-01T00:00:00.000Z",
    "endTime": "2025-01-01T00:00:01.250Z",
    "duration": 1250
  }
}

status is included when the engine reports one (success, failed, cancelled, or paused). A failed execution returns the same shape with success: false, an error message, and HTTP 500.

If the workflow ends in a Response block, the API returns the body, status code, and headers that block authored instead, and sets X-SteelEngine-Response-Type: response. Every execution response also carries the execution ID in the X-Execution-Id header.

Execution responses do not include rate limit or usage information. The /api/v1 workflows, logs, and audit logs endpoints attach a limits object with workflowExecutionRateLimit and usage. For everything else, call Get Usage Limits.

Error Handling

The API uses standard HTTP status codes. Error responses include a human-readable error message:

{
  "error": "Workflow not found"
}
StatusMeaningWhat to do
400Invalid request parametersCheck the details array for specific field errors. code: "INVALID_SELECTED_OUTPUT" means a selectedOutputs entry names no existing block or field
401Missing or invalid API keyVerify your X-API-Key header
402Usage limit exceededThe billed account has spent its budget for the period. Check Get Usage Limits for the current spend and limit
403Access deniedCheck you have permission for this resource and that the key's scope covers it
404Resource not foundVerify the ID exists and belongs to your workspace
409ConflictThe workflow call chain is invalid, or the workflow's environment promotion binding rejected the run
429Rate limit exceededBack off and retry; see Rate Limits for which responses carry Retry-After
503Result unavailableThe run was admitted but its result could not be recovered (code: "RESULT_UNAVAILABLE"). Poll the statusUrl in the body instead of resubmitting

Use the Get Usage Limits endpoint to check your current rate limit status and billing usage at any time.

Rate Limits

Rate limits depend on your subscription plan. Self-hosted deployments with billing disabled use the enterprise limits for every account: 600 sync, 5000 async, and 500 API endpoint requests per minute by default, with the sync and async limits overridable through RATE_LIMIT_ENTERPRISE_SYNC and RATE_LIMIT_ENTERPRISE_ASYNC. Your account has a sync bucket and an async bucket, both reported by Get Usage Limits as requestsPerMinute, maxBurst, remaining, and resetAt. The execute endpoint counts synchronous and streaming executions against the sync bucket, and requests sent with X-Execution-Mode: async against the async bucket.

When you are rate limited, the execute endpoint returns 429 with {"error": "Rate limit exceeded. Please try again later."}. This response has no Retry-After header. Back off and check resetAt from Get Usage Limits before you retry. A 429 that carries Retry-After: 5 means the server admission gate is at capacity, not that your bucket is empty.

The /api/v1 workflows, logs, audit logs, tables, docs, and knowledge base endpoints share a separate API request limit (the API endpoint limit above). It is counted per user, across every API key that user owns, not per key. When it runs out, these endpoints return 429 with Retry-After and the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. The workflows, logs, and audit logs endpoints, and every paginated list endpoint for tables, rows, docs, doc folders, knowledge bases, and knowledge base documents, also send those headers on successful responses. The other tables, docs, and knowledge base endpoints send them only on 429. Send Chat Message counts against the same limit and sends those headers on 429. The /api/v1/workspaces endpoints do not count against this limit.

Pagination

The /api/v1 list endpoints below page with a cursor. Send limit for the page size and pass the previous response's nextCursor back as cursor to get the next page. The cursor is an opaque token. List Workflows, Query Logs, and List Audit Logs ignore a cursor they cannot read and return the first page. The other list endpoints return 400 for it.

EndpointWithout limit or cursorPage size
List WorkflowsFirst pageDefault 50, max 100
Query LogsFirst pageDefault 100
List Audit LogsFirst pageDefault 50, max 100
List WorkspacesFirst pageDefault 50, max 250
List RowsFirst pageDefault 100, max 1000
List DocumentsFirst pageDefault 50, max 100
List TablesWhole listDefault 50, max 100
List Knowledge BasesWhole listDefault 50, max 100
List DocsWhole listDefault 100, max 200
List Doc FoldersWhole listDefault 100, max 200

List Tables, List Knowledge Bases, List Docs, and List Doc Folders return every item when you send neither limit nor cursor, so existing callers keep working. Send either one to get pages. Their responses still carry totalCount for the whole list.

List Workspaces, List Rows, and List Documents still accept the older offset parameter, but it is deprecated. When you send both, cursor wins. Their responses keep the offset fields (totalCount, and pagination for List Documents) next to nextCursor.

List Paused Executions is not under /api/v1 and is not paginated. It returns the whole list.

# First page
curl "https://dev.steelengine.com/api/v1/logs?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

# Next page: use the nextCursor from the previous response
curl "https://dev.steelengine.com/api/v1/logs?limit=20&cursor=abc123" \
  -H "X-API-Key: YOUR_API_KEY"

When nextCursor is absent or null, you have reached the last page.

On this page