Orchestrator API Reference

All Orchestrator APIs are served from https://orchestrator.skytells.ai. Management APIs use session-based authentication (cookie). The webhook endpoint uses API key authentication.

Workflows

List Workflows

GET /api/workflows

Returns all workflows owned by the authenticated user, ordered by most recent first.

Response: Array of workflow objects with id, name, description, visibility, createdAt, updatedAt.

Create Workflow

POST /api/workflows/create

Create a new workflow. If no trigger node is provided, a default Manual trigger is added automatically.

Body:

{
  "name": "My Workflow",
  "description": "Optional description",
  "nodes": [],
  "edges": []
}

Get Workflow

GET /api/workflows/{workflowId}

Returns the full workflow including nodes and edges. Public workflows are accessible to non-owners but with integration references sanitized.

Update Workflow

PATCH /api/workflows/{workflowId}

Update workflow properties. Owner only.

Body (all fields optional):

{
  "name": "Updated Name",
  "description": "Updated description",
  "nodes": [...],
  "edges": [...],
  "visibility": "public"
}

Delete Workflow

DELETE /api/workflows/{workflowId}

Permanently delete a workflow. Owner only.

Duplicate Workflow

POST /api/workflows/{workflowId}/duplicate

Create a copy of a workflow with new node IDs. Integration references are stripped. The duplicate is always set to private visibility.

Executions

List Executions

GET /api/workflows/{workflowId}/executions

Returns the 50 most recent execution records for a workflow. Owner only.

Response: Array of execution objects with id, status, input, output, error, startedAt, completedAt, duration.

Get Execution Status

GET /api/workflows/executions/{executionId}/status

Returns the current execution status and per-node status.

Response:

{
  "id": "exec_abc123",
  "status": "success",
  "nodeStatuses": {
    "node1": "success",
    "node2": "success"
  }
}

Get Execution Logs

GET /api/workflows/executions/{executionId}/logs

Returns detailed per-step execution logs. Input and output data is automatically redacted (API keys, auth headers, and sensitive data are stripped).

Response: Array of log entries:

[
  {
    "id": "log_xyz",
    "nodeId": "node1",
    "nodeName": "Generate Text",
    "nodeType": "action",
    "status": "success",
    "input": { "prompt": "..." },
    "output": { "text": "..." },
    "error": null,
    "startedAt": "2025-01-15T10:00:00Z",
    "completedAt": "2025-01-15T10:00:02Z",
    "duration": "2000"
  }
]

Delete Execution Logs

DELETE /api/workflows/{workflowId}/executions

Delete all execution records and logs for a workflow. Owner only.

Webhook Trigger

Execute via Webhook

POST /api/workflows/{workflowId}/webhook

Authentication: Authorization: Bearer wfb_<key>

Body: Any valid JSON (becomes trigger input).

Response (200):

{
  "executionId": "exec_abc123",
  "status": "running"
}

Error responses: 400 (trigger mismatch), 401 (invalid key), 403 (wrong owner), 404 (not found), 500 (runtime error).

See Webhooks for full details and examples.

CORS Preflight

OPTIONS /api/workflows/{workflowId}/webhook

Returns CORS headers allowing requests from any origin.

Integrations

List Integrations

GET /api/integrations

Returns all integrations for the authenticated user. Config (credentials) is excluded from the response for security.

Query parameters:

• type (optional) — Filter by integration type (e.g., skytells, slack)

Create Integration

POST /api/integrations

Body:

{
  "name": "My Slack Connection",
  "type": "slack",
  "config": {
    "apiKey": "xoxb-your-slack-token"
  }
}

The config object is encrypted with AES-256-GCM before storage.

Get Integration

GET /api/integrations/{integrationId}

Returns the integration with decrypted config. Owner only.

Update Integration

PUT /api/integrations/{integrationId}

Update integration config. The new config is re-encrypted before storage.

Delete Integration

DELETE /api/integrations/{integrationId}

Delete an integration. Actions using this integration will lose their connection.

Test Integration

POST /api/integrations/{integrationId}/test

Test the integration credentials by calling the provider's API. Returns success/failure status.

API Keys

List API Keys

GET /api/api-keys

Returns metadata for all Orchestrator API keys owned by the current user:

[
  {
    "id": "key_abc",
    "name": "production",
    "keyPrefix": "wfb_abc1234",
    "createdAt": "2025-01-15T10:00:00Z",
    "lastUsedAt": "2025-01-16T08:30:00Z"
  }
]

The full key is never returned after creation.

Create API Key

POST /api/api-keys

Body:

{
  "name": "production-webhook-key"
}

Response:

{
  "id": "key_abc",
  "name": "production-webhook-key",
  "key": "wfb_aB3cD4eF5gH6iJ7kL8mN9oP0q",
  "keyPrefix": "wfb_aB3cD4e",
  "createdAt": "2025-01-15T10:00:00Z"
}

Anonymous users cannot create API keys.

Code Export

Generate Code

GET /api/workflows/{workflowId}/code

Returns the generated TypeScript SDK code for the workflow as a text response.

Download Project

GET /api/workflows/{workflowId}/download

Returns a ZIP file containing a complete Next.js project with the workflow code, API route, and dependencies.

See Code Export for details.

AI Generation

Generate Workflow

POST /api/ai/generate

Streams JSONL operations that build a workflow from a natural language description.

Body:

{
  "prompt": "Create a workflow that scrapes a URL and summarizes the content"
}

Response: Streamed JSONL, one operation per line:

{"op": "setName", "name": "URL Scraper and Summarizer"}
{"op": "setDescription", "description": "..."}
{"op": "addNode", "node": { ... }}
{"op": "addEdge", "edge": { ... }}

See AI Generation for details.

User

Get Current User

GET /api/user

Returns the authenticated user's profile: id, name, email, image, isAnonymous, providerId.

Update Profile

PATCH /api/user

Body:

{
  "name": "New Name"
}

OAuth users (GitHub, Google) cannot update their profile name.

Authentication

All management APIs (everything except the webhook endpoint) use session-based authentication via cookies set by the Supabase Auth system.

The webhook endpoint (POST /api/workflows/{workflowId}/webhook) uses API key authentication via the Authorization: Bearer wfb_... header. See API Keys.

Next Steps