API Reference

Reference conventions

Availability gates: Some APIs and tasks are available only when the feature is enabled on your cluster. Contact Orkes support to enable them.
Deprecation: Deprecated routes and task types are retained only for migration guidance. Use the documented replacement for new integrations.
Definitions vs. runtime: Workflow and task definitions are reusable blueprints; workflow and task objects are individual execution records. See Schemas for the field-level contract.

Authentication

Every request to Orkes Conductor requires an X-Authorization header containing a valid JSON Web Token (JWT). Generate a JWT from an application's access key and secret, then send it with every API call. See Authentication and Access Keys for how to create an application, retrieve an access key, and generate a token.

Base URL

All API endpoints are relative to your Conductor cluster's base URL:

<YOUR-CLUSTER-URL>/api/

For example, to list all workflow definitions:

curl <YOUR-CLUSTER-URL>/api/metadata/workflow \
  -H 'X-Authorization: <YOUR-JWT>'

Replace <YOUR-CLUSTER-URL> with the URL of your cluster, and <YOUR-JWT> with a JWT generated from your application's access key and secret.

Content Type

All request and response bodies use JSON. Set the following headers on requests with a body:

Content-Type: application/json

A few endpoints return plain text (for example, the workflow ID on start). These are noted in their documentation.

Common Response Codes

Status Code	Description
`200 OK`	Request succeeded. The response body contains the result.
`204 No Content`	Request succeeded but there is no response body (for example, poll with no tasks available).
`400 Bad Request`	Invalid request. Check your request body or parameters.
`404 Not Found`	The requested resource (workflow, task, definition) does not exist.
`409 Conflict`	Conflict with current state (for example, trying to resume a workflow that is not paused).
`500 Internal Server Error`	Server-side error. Retry the request, and contact Orkes support if the error persists.

Error Response Format

When an error occurs, the response body contains:

{
  "status": 404,
  "message": "No such workflow found by name: my_workflow, version: null",
  "instance": "<SERVER-ID>",
  "retryable": false
}

instance is the name of the server that handled the request. Some errors also include a metadata field with extra details.

Validation errors (400) return the message and a list of the fields that failed:

{
  "message": "WorkflowTask list cannot be empty",
  "validationErrors": [
    {
      "path": "tasks",
      "message": "WorkflowTask list cannot be empty"
    }
  ]
}

Some APIs, such as those for applications and users, return only a message field.

Quick Start

Register a workflow definition, start it, and check its status in three commands:

# 1. Register a workflow definition
curl -X POST '<YOUR-CLUSTER-URL>/api/metadata/workflow' \
  -H 'X-Authorization: <YOUR-JWT>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "hello_workflow",
    "version": 1,
    "tasks": [
      {
        "name": "hello_task",
        "taskReferenceName": "hello_ref",
        "type": "HTTP",
        "inputParameters": {
          "http_request": {
            "uri": "https://jsonplaceholder.typicode.com/posts/1",
            "method": "GET"
          }
        }
      }
    ],
    "schemaVersion": 2
  }'

# 2. Start a workflow execution
WORKFLOW_ID=$(curl -s -X POST '<YOUR-CLUSTER-URL>/api/workflow/hello_workflow' \
  -H 'X-Authorization: <YOUR-JWT>' \
  -H 'Content-Type: application/json' \
  -d '{}')
echo "Started workflow: $WORKFLOW_ID"

# 3. Check workflow status
curl "<YOUR-CLUSTER-URL>/api/workflow/$WORKFLOW_ID" \
  -H 'X-Authorization: <YOUR-JWT>'

API Sections

Section	Base Path	Description
Authentication	`/api/token`	Create an application access key and generate a JWT for API access.
Conductor Agents	`/api/agent`	Compile, deploy, start, observe, and control SDK-authored durable agents.
Bulk Operations	`/api/workflow/bulk`	Pause, resume, restart, retry, terminate, or remove workflows in batch.
Files	`/api/files`	Create workflow-scoped file handles and exchange signed upload and download URLs.
Metadata	`/api/metadata`	Register, update, validate, and delete workflow and task definitions.
Tasks	`/api/tasks`	Poll for tasks, update results, manage queues, view logs, search.
Workflows	`/api/workflow`	Start workflows and manage executions: get status, pause, resume, retry, restart, terminate, search.
Users	`/api/users`	Create, update, delete, and look up users and their permissions.
Groups	`/api/groups`	Manage groups and their members.
Applications	`/api/applications`	Manage applications, their access keys, and roles.
Tags	`/api/metadata`	Add, update, and remove tags on workflow and task definitions.
Secrets	`/api/secrets`	Create and manage secrets, and their tags.
Tokens	`/api/token`	Generate and manage authentication tokens.
Authorization	`/api/auth`	Grant and revoke access, and get access grants for a resource.
Schema	`/api/schema`	Create, read, and delete schema definitions.
Environment Variables	`/api/environment`	Create and manage environment variables, and their tags.
Schedule	`/api/scheduler`	Create, search, pause, resume, and bulk-manage schedules.
Webhook	`/api/metadata/webhook`	Create and manage webhook definitions, and their tags.
Human Task	`/api/human`	Manage human tasks and user forms.
Remote Services	`/api/registry`	Register remote services and their methods.
Integrations	`/api/integrations`	Manage integration providers, models, and their tags.
Prompts	`/api/prompts`	Create and manage AI prompts, and their tags.
Gateway	`/api/gateway`	Manage API gateway services, routes, and auth configs.

Swagger UI

The Swagger UI at <YOUR-CLUSTER-URL>/swagger-ui/index.html provides an interactive API explorer where you can try endpoints directly from your browser.

SDKs

For programmatic access, use one of the official Conductor SDKs, which wrap these REST APIs with language-native interfaces for Java, Python, Go, JavaScript, C#, Ruby, and Rust.