This document provides comprehensive reference documentation for the Sim platform's REST API endpoints. These APIs enable programmatic workflow execution, webhook handling, scheduled runs, and execution monitoring.
For authentication setup and credential management, see Authentication System. For SDK usage (TypeScript and Python), refer to the SDKs referenced in the monorepo structure. For workflow creation and management, see Workflows & Blocks.
The Sim platform exposes REST API endpoints for workflow management, execution, and monitoring. All endpoints follow REST conventions and return JSON responses (except SSE streaming endpoints).
| Category | Endpoints | Purpose |
|---|---|---|
| Workflow Management | GET/POST/PUT/DELETE /api/workflows/* | Create, read, update, delete workflows |
| Workflow State | PUT /api/workflows/:id/state | Save complete workflow graph state to normalized tables |
| Workflow Execution | POST /api/workflows/:id/execute | Execute workflows with multiple modes (sync/async/streaming) |
| Webhook Triggers | POST /api/webhooks/trigger/:path | Receive webhook events from external services |
| Schedule Execution | GET /api/schedules/execute | Internal cron endpoint for scheduled workflows |
| Execution Logging | POST /api/workflows/:id/log | Persist execution results and traces |
| Deployment | POST /api/workflows/:id/deploy | Deploy workflow versions |
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:1-945, apps/sim/app/api/workflows/[id]/state/route.ts:1-294, apps/sim/app/api/workflows/[id]/route.ts:1-280, apps/sim/lib/workflows/executor/execution-core.ts1-434
The API supports three authentication mechanisms depending on the endpoint:
The workflow execution endpoint uses hybrid authentication that accepts either session cookies or API keys. This is handled by checkHybridAuth.
| Method | Header | Use Case |
|---|---|---|
| Session | Cookie: session=... | Web UI executions |
| API Key | Authorization: Bearer {api_key} | Programmatic access via SDKs |
| Internal JWT | Authorization: Bearer {jwt} | Internal service-to-service calls |
The authType returned by checkHybridAuth determines input handling behavior:
input field explicitlySources: apps/sim/lib/auth/hybrid.ts apps/sim/app/api/workflows/[id]/execute/route.ts:183-246
Webhooks use provider-specific signature verification:
Each provider has specific signature validation requirements configured in the webhook's providerConfig.
Sources: apps/sim/lib/webhooks/processor.ts450-784
Schedule execution endpoint requires an internal authorization header validated by verifyCronAuth. This prevents unauthorized triggering of scheduled workflows.
Sources: apps/sim/app/api/schedules/execute/route.ts19-22
POST /api/workflows/:id/execute
The primary API for executing workflows. Supports multiple execution modes: synchronous streaming (SSE), synchronous JSON, and asynchronous background execution.
The request body is validated using ExecuteWorkflowSchema:
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:44-81
The endpoint supports three execution modes determined by headers and body parameters:
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:223-630
Enable streaming by setting X-Stream-Response: true header or stream: true in body.
Response Headers:
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Execution-Id: {executionId}
Event Stream Format:
Events are encoded using encodeSSEEvent and follow the Server-Sent Events specification:
| Event Type | Description | Data Fields |
|---|---|---|
execution:started | Workflow execution began | {startTime, executionId, workflowId} |
block:started | Block execution started | {blockId, blockName, blockType, executionOrder, iterationCurrent?, iterationTotal?, iterationType?} |
block:completed | Block completed successfully | {blockId, blockName, blockType, input, output, durationMs, startedAt, endedAt, executionOrder, iterationContext?} |
block:error | Block execution failed | {blockId, blockName, blockType, input, error, durationMs, startedAt, endedAt, executionOrder} |
stream:chunk | Streaming content chunk from LLM | {blockId, chunk} |
stream:done | LLM stream complete | {blockId} |
execution:completed | Workflow finished successfully | {success: true, output, duration, startTime, endTime} |
execution:error | Workflow failed | {error, duration} |
execution:cancelled | Execution was cancelled | {duration} |
Example event:
data: {"type":"block:completed","timestamp":"2024-01-01T00:00:00.000Z","executionId":"abc-123","workflowId":"wf-xyz","data":{"blockId":"block-1","blockName":"Agent","blockType":"agent","input":{},"output":{"content":"Hello"},"durationMs":120,"startedAt":"2024-01-01T00:00:00.000Z","endedAt":"2024-01-01T00:00:00.120Z","executionOrder":1}}
Callback Integration:
The SSE stream is generated by wrapping execution callbacks:
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:637-920, apps/sim/lib/workflows/executor/execution-events.ts1-120
Default mode when streaming is not enabled. Returns complete execution result in single response.
Response (200 OK):
If workflow contains a Response block, returns HTTP response with custom status/headers/body instead.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:408-497
Enable by setting X-Execution-Mode: async header. Requires TRIGGER_DEV_ENABLED=true.
Response (202 Accepted):
The execution runs in background via Trigger.dev. Use the statusUrl or SDK to poll for results.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:126-170
Input resolution depends on authentication type:
API Key/Internal JWT Input Example:
Session Input Example:
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:258-296, apps/sim/app/api/workflows/[id]/execute/route.ts:372-426
Every execution goes through preprocessExecution which performs validation and authorization checks:
Preprocessing Options:
Sources: apps/sim/lib/execution/preprocessing.ts50-415
| Status | Error | Description |
|---|---|---|
| 400 | Invalid request body | Schema validation failed |
| 401 | Unauthorized | Missing or invalid authentication |
| 402 | Payment Required | Usage limits exceeded |
| 403 | Forbidden | Workflow not deployed or access denied |
| 404 | Not Found | Workflow doesn't exist |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Execution or system error |
Sources: apps/sim/lib/execution/preprocessing.ts134-150
PUT /api/workflows/:id/state
Saves complete workflow state to normalized database tables. This endpoint is called by the web UI during collaborative editing to persist workflow graph changes.
The request body is validated using WorkflowStateSchema:
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:18-109
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:115-276
The state is persisted across multiple tables:
| Table | Purpose | Key Fields |
|---|---|---|
workflowBlocks | Individual blocks | workflowId, blockId, type, name, position, subBlocks |
workflowEdges | Connections between blocks | workflowId, edgeId, source, target, sourceHandle, targetHandle |
workflowSubflows | Loop and parallel containers | workflowId, subflowId, type, nodes, config |
This normalized structure enables efficient querying and collaborative editing features.
Sources: apps/sim/lib/workflows/persistence/utils.ts
When a workflow state is saved, custom tools defined in agent blocks are extracted and persisted to the customTools table for workspace-wide reuse:
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:206-235, apps/sim/lib/workflows/persistence/custom-tools-persistence.ts
After successful state save, the endpoint notifies the Socket.IO server to broadcast the update to other connected clients:
This enables real-time collaborative editing where multiple users see each other's changes immediately.
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:253-274
GET /api/workflows/:id
Fetches a single workflow by ID, including its complete state loaded from normalized tables.
Uses checkHybridAuth to support three authentication methods:
Authorization: Bearer {key} or x-api-key: {key} headerInternal calls without userId are allowed for system executions.
Sources: apps/sim/app/api/workflows/[id]/route.ts:29-142
PUT /api/workflows/:id
Updates workflow metadata fields (name, description, color, folder assignment, sort order).
Requires write permission via authorizeWorkflowByWorkspacePermission:
Sources: apps/sim/app/api/workflows/[id]/route.ts:347-428
DELETE /api/workflows/:id
Deletes a workflow. Includes safety checks and cleanup of associated resources.
The endpoint supports two-phase deletion for workflows with published templates:
?check-templates=true returns template information?deleteTemplates=delete|orphan determines template handling
delete: Delete all associated templatesorphan: Set workflowId to null on templatesBefore deletion, the system:
cleanupExternalWebhookSources: apps/sim/app/api/workflows/[id]/route.ts:144-345
GET /api/workflows
Retrieves all workflows for a workspace or user.
| Parameter | Type | Description |
|---|---|---|
workspaceId | string | Optional. Filter by workspace. If not provided, returns all workflows user has access to. |
workspaceId provided: Verifies workspace membership via verifyWorkspaceMembershipworkspaceId: Returns workflows from all workspaces user has permissions forWorkflows are ordered by sortOrder ASC, createdAt ASC, id ASC.
Sources: apps/sim/app/api/workflows/route.ts24-96
POST /api/workflows
Creates a new workflow in a workspace.
When sortOrder is not provided, the system calculates it to place the new workflow at the top:
Requires workspace write or admin permission via getUserEntityPermissions.
Sources: apps/sim/app/api/workflows/route.ts99-216
POST /api/workflows/:id/duplicate
Creates a complete copy of a workflow including all blocks, edges, subflows, and variables.
The duplication process maintains referential integrity by:
parentId for nested blockssourceBlockId and targetBlockId to new block IDsnodes arrayworkflowId referenceSources: apps/sim/app/api/workflows/[id]/duplicate/route.ts:1-96, apps/sim/lib/workflows/persistence/duplicate.ts40-316
POST /api/webhooks/trigger/:path
GET /api/webhooks/trigger/:path
Receives webhooks from external services. The :path parameter is a unique identifier for the webhook configuration.
Sources: apps/sim/app/api/webhooks/trigger/[path]/route.ts:37-176
Many providers send verification requests before accepting the webhook:
| Provider | Challenge Type | Handler |
|---|---|---|
| Slack | challenge field in body | handleSlackChallenge |
hub.mode, hub.verify_token, hub.challenge query params | handleWhatsAppVerification | |
| Microsoft Graph | validationToken query param | Returns token as plain text |
Sources: apps/sim/lib/webhooks/processor.ts141-174
Each provider has specific signature verification:
X-Hub-Signature-256: sha256=<hmac>
X-Hub-Signature: sha1=<hmac> (legacy)
Validates HMAC using configured secret.
X-Slack-Signature: v0=<signature>
X-Slack-Request-Timestamp: <timestamp>
Validates signature against timestamp and body.
X-Twilio-Signature: <signature>
Validates against URL and form parameters.
Supports two authentication modes:
Authorization: Bearer {token}Sources: apps/sim/lib/webhooks/processor.ts450-784
Webhooks support credential set fan-out where multiple webhooks share the same path but use different credentials. The system processes each webhook independently.
Sources: apps/sim/lib/webhooks/processor.ts366-407
Webhooks always execute asynchronously via webhook-execution Trigger.dev task:
Job Payload:
Sources: apps/sim/background/webhook-execution.ts81-92
Uses fetchAndProcessAirtablePayloads to fetch actual record changes from Airtable API using webhook metadata.
Filters out status updates, only processes actual messages.
Processes files based on inputFormat configuration with type: 'files' fields.
Sources: apps/sim/background/webhook-execution.ts165-318 apps/sim/background/webhook-execution.ts412-457
GET /api/schedules/execute
Internal cron endpoint that processes due scheduled workflows. Requires internal authorization.
Sources: apps/sim/app/api/schedules/execute/route.ts15-133
Uses optimistic locking via lastQueuedAt timestamp to prevent duplicate execution:
Sources: apps/sim/app/api/schedules/execute/route.ts27-53
Sources: apps/sim/background/schedule-execution.ts273-283
Schedules track consecutive failures and auto-disable after MAX_CONSECUTIVE_FAILURES (typically 3):
| Failure Type | Status Code | Action |
|---|---|---|
| Authentication (401) | 401 | Disable schedule immediately |
| Authorization (403) | 403 | Disable schedule immediately |
| Workflow Not Found (404) | 404 | Disable schedule immediately |
| Rate Limit (429) | 429 | Retry after 5 minutes |
| Usage Limit (402) | 402 | Schedule next normal run |
| Other Errors | 500 | Increment failure count, retry next cycle |
Sources: apps/sim/background/schedule-execution.ts348-466
The platform provides comprehensive logging and analytics endpoints for execution monitoring, filtering, and export.
GET /api/logs
Main endpoint for fetching workflow execution logs with advanced filtering and search capabilities.
| Parameter | Type | Description |
|---|---|---|
workspaceId | string | Required. Workspace ID to query |
details | basic | full | Default: basic. Controls response detail level |
limit | number | Default: 100. Max results per page |
offset | number | Default: 0. Pagination offset |
level | string | Filter by level(s): error, info, running, pending (comma-separated) |
workflowIds | string | Filter by workflow ID(s) (comma-separated) |
folderIds | string | Filter by folder ID(s) (comma-separated) |
triggers | string | Filter by trigger type(s) (comma-separated) |
startDate | string | ISO timestamp for date range start |
endDate | string | ISO timestamp for date range end |
search | string | Full-text search in execution data |
costOperator | > | < | >= | <= | Cost comparison operator |
costValue | number | Cost value for filtering |
durationOperator | > | < | >= | <= | Duration comparison operator |
durationValue | number | Duration value (ms) for filtering |
workflowName | string | Filter by workflow name |
folderName | string | Filter by folder name |
executionId | string | Filter by specific execution ID |
The level parameter supports advanced state filtering:
error: Failed executionsinfo: Completed successful executionsrunning: Currently executing (no endedAt)pending: Paused executions (human-in-the-loop)Basic Detail Level:
Full Detail Level:
Includes additional fields:
executionData.traceSpans: Hierarchical execution tracesexecutionData.blockExecutions: Block-level execution detailsexecutionData.finalOutput: Final workflow outputcost: Full cost breakdown by modelfiles: Associated file attachmentsSources: apps/sim/app/api/logs/route.ts1-400 apps/sim/lib/logs/filters.ts
GET /api/v1/logs
Stable V1 API endpoint with cursor-based pagination for efficient log streaming.
| Parameter | Type | Description |
|---|---|---|
workspaceId | string | Required. Workspace ID |
workflowIds | string | Filter by workflow ID(s) (comma-separated) |
folderIds | string | Filter by folder ID(s) (comma-separated) |
triggers | string | Filter by trigger type(s) (comma-separated) |
level | info | error | Filter by level |
startDate | string | ISO timestamp |
endDate | string | ISO timestamp |
executionId | string | Specific execution ID |
minDurationMs | number | Minimum duration filter |
maxDurationMs | number | Maximum duration filter |
minCost | number | Minimum cost filter |
maxCost | number | Maximum cost filter |
model | string | Filter by AI model used |
details | basic | full | Default: basic |
includeTraceSpans | boolean | Default: false |
includeFinalOutput | boolean | Default: false |
limit | number | Default: 100. Max: 1000 |
cursor | string | Pagination cursor (base64-encoded) |
order | desc | asc | Default: desc |
The V1 API uses cursor-based pagination instead of offset-based:
Cursor encodes {startedAt, id} for stable pagination:
V1 API enforces rate limits with headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000
Sources: apps/sim/app/api/v1/logs/route.ts1-210
GET /api/logs/export
Exports execution logs as CSV with streaming response.
Accepts same filter parameters as GET /api/logs.
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="logs-YYYY-MM-DDTHH-mm-ss-sssZ.csv"
Cache-Control: no-cache
CSV Columns:
| Column | Description |
|---|---|
startedAt | Execution start timestamp |
level | Log level (info/error) |
workflow | Workflow name |
trigger | Trigger type |
durationMs | Execution duration in milliseconds |
costTotal | Total cost |
workflowId | Workflow identifier |
executionId | Execution identifier |
message | Output message or error |
traceSpans | JSON-serialized trace spans |
Uses ReadableStream with pagination to handle large exports:
Sources: apps/sim/app/api/logs/export/route.ts1-151
GET /api/logs/triggers
Returns unique trigger types from execution logs, excluding core trigger types.
| Parameter | Type | Description |
|---|---|---|
workspaceId | string | Required. Workspace ID |
Excludes core triggers: api, manual, webhook, chat, schedule
Sources: apps/sim/app/api/logs/triggers/route.ts1-86
The logs API supports a structured query language for advanced filtering:
field:value [field:operator value] [text search]
Supported Fields:
| Field | Type | Operators | Examples |
|---|---|---|---|
level | string | = | level:error, level:info |
trigger | string | = | trigger:api, trigger:webhook |
workflow | string | = | workflow:"My Workflow" |
folder | string | = | folder:"Production" |
workflowId | string | = | workflowId:abc-123 |
executionId | string | = | executionId:exec-xyz |
cost | number | >, <, >=, <=, = | cost:>0.01, cost:=0 |
duration | number | >, <, >=, <= | duration:>5s, duration:<1s |
date | date | = | date:today, date:2024-01-15, date:2024-01-01..2024-01-31 |
Date Formats:
today, yesterday, this-week, last-week, this-month20242024-122024-12-152024-01-01..2024-01-31Duration Units:
500ms5sExample Queries:
level:error cost:>0.01
workflow:"Production API" date:this-week
trigger:webhook duration:>10s
The parseQuery function converts search strings to structured filters:
The search system provides intelligent autocomplete via SearchSuggestions class:
Suggestion Categories:
level:error, cost:>0.01)Sources: apps/sim/lib/logs/query-parser.ts1-304 apps/sim/lib/logs/search-suggestions.ts1-674
GET /api/workspaces
Retrieves all workspaces the authenticated user has access to.
If user has no workspaces, the system automatically creates a default workspace and migrates orphaned workflows:
Sources: apps/sim/app/api/workspaces/route.ts20-56
POST /api/workspaces
Creates a new workspace for the authenticated user.
The default workflow includes a pre-configured agent block setup.
Sources: apps/sim/app/api/workspaces/route.ts59-169
Successful responses follow this structure:
Sources: apps/sim/app/api/workflows/utils.ts
Files in workflow input/output are represented as:
Sources: apps/sim/lib/uploads/types.ts
Rate limits are enforced per user/workspace using token bucket algorithm implemented in RateLimiter class:
| Plan | Sync (req/min) | Async (req/min) | API Endpoint (req/min) |
|---|---|---|---|
| Free | 10 | 50 | 10 |
| Pro | 25 | 200 | 30 |
| Team | 75 | 500 | 60 |
| Enterprise | 150 | 1000 | 120 |
Request Type Classification:
/api/workflows/:id/execute callsSources: apps/sim/lib/core/rate-limiter/types.ts29-50
Execution timeouts vary by plan and execution mode:
| Plan | Sync Timeout | Async Timeout |
|---|---|---|
| Free | 60s | 300s (5 min) |
| Pro | 120s | 900s (15 min) |
| Team | 300s | 1800s (30 min) |
| Enterprise | 600s | 3600s (60 min) |
Timeouts are enforced using AbortController:
Sources: apps/sim/lib/core/execution-limits.ts1-150 apps/sim/app/api/workflows/[id]/execute/route.ts:456-495
Rate limit information is included in preprocessing response:
Sources: apps/sim/lib/execution/preprocessing.ts145-149
HTTP 429 Too Many Requests
{
"error": "Rate limit exceeded. Please try again later."
}
Clients should respect the rate limit and implement exponential backoff.
Sources: apps/sim/lib/core/rate-limiter/types.ts52-59
Every execution includes comprehensive metadata for tracking and debugging:
Sources: apps/sim/executor/execution/types.ts5-28
The platform supports human-in-the-loop executions that can pause and resume. This is managed through the PauseResumeManager.
When a workflow pauses, a complete snapshot is persisted:
Resumes are queued and processed serially per execution:
Sources: apps/sim/lib/workflows/executor/human-in-the-loop-manager.ts1-160
All async executions use Trigger.dev for reliable background processing:
Task ID: workflow-execution
Sources: apps/sim/background/workflow-execution.ts17-24
Task ID: webhook-execution
Idempotency is enforced using provider-specific keys to prevent duplicate processing.
Sources: apps/sim/background/webhook-execution.ts94-122
Task ID: schedule-execution
Handles retry logic and failure tracking for scheduled workflows.
Sources: apps/sim/background/schedule-execution.ts598-604
Workflows can return custom HTTP responses using the Response block:
When a Response block is present, the API returns the custom response instead of the standard JSON envelope.
Sources: apps/sim/lib/workflows/utils.ts apps/sim/app/api/workflows/[id]/execute/route.ts:458-460
For programmatic access, use the official SDKs:
simstudio-ts-sdk packagesimstudio-python-sdk packagesimstudio npm packageThese provide typed interfaces, automatic retries, and simplified authentication management.
Sources: Monorepo structure references in overview diagrams
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.