API Deployment

Deploy your workflow as a REST API endpoint that any application can call directly. Supports synchronous, streaming, and asynchronous execution modes.

Deploying a Workflow

Open your workflow and click Deploy. The General tab opens first and shows you the current deployment state:

The General tab contains:

• Live Workflow — a read-only minimap of the workflow snapshot that is currently deployed
• Versions — a table of every deployment you've published, showing version number, who deployed it, and when
• Deploy / Update / Undeploy — action buttons at the bottom right

Click Deploy to publish your workflow for the first time, or Update to push a new snapshot after making changes. The green dot next to a version indicates it is the currently live version.

Once deployed, your workflow is available at:

POST https://sim.ai/api/workflows/{workflow-id}/execute

Keeping Track of Changes

When you modify the workflow canvas after deploying, an Update deployment badge appears at the bottom of the screen as a reminder that your live version is out of date:

You can click the Update button directly from the canvas toolbar — you don't need to open the Deploy modal every time.

Version Control

Every time you deploy or update, a new version is recorded in the Versions table. You can manage past versions using the context menu (⋮) next to any row:

Promote to live is useful for rolling back — if a new deployment has an issue, promote the previous version to restore the last known-good state instantly.

Making API Calls

Switch to the API tab in the Deploy modal to see ready-to-use code for all three execution modes:

The language selector at the top lets you switch between cURL, Python, JavaScript, and TypeScript. Each mode — synchronous, streaming, and async — has its own code block that you can copy directly. The code is pre-filled with your workflow ID and a masked version of your API key.

At the bottom of the tab, two buttons give you quick access to key settings:

• Edit API Info — set a description and choose between API key auth or public access
• Generate API Key — create a new API key scoped to your workspace

Authentication

By default, API endpoints require an API key passed in the x-api-key header. Generate keys in Settings → Sim Keys or via the Generate API Key button in the API tab.

curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIM_API_KEY" \
  -d '{ "input": "Hello" }'

API Info and Public Access

Click Edit API Info to add a description and change the access mode:

The Description field documents what the workflow API does. This is useful for teams, or when exposing the workflow to tools and services that surface API metadata.

Execution Modes

Synchronous

The default mode. Send a request and wait for the complete response:

curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIM_API_KEY" \
  -d '{ "input": "Summarize this article" }'

import requests, os

response = requests.post(
    "https://sim.ai/api/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["SIM_API_KEY"]
    },
    json={"input": "Summarize this article"}
)
print(response.json())

const response = await fetch('https://sim.ai/api/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.SIM_API_KEY!
  },
  body: JSON.stringify({ input: 'Summarize this article' })
});
console.log(await response.json());

Streaming

Stream the response token-by-token as it is generated. Add "stream": true to your request body and specify which block output fields to stream using selectedOutputs.

Use the Select outputs dropdown in the API tab to choose which fields to stream:

The dropdown groups available outputs by block. The most common choice is content from an Agent block, which streams the generated text. You can select fields from multiple blocks simultaneously.

The selectedOutputs values in the request body follow the format blockName.field (e.g., agent_1.content).

curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIM_API_KEY" \
  -d '{
    "input": "Write a long essay",
    "stream": true,
    "selectedOutputs": ["agent_1.content"]
  }'

import requests, os

response = requests.post(
    "https://sim.ai/api/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["SIM_API_KEY"]
    },
    json={
        "input": "Write a long essay",
        "stream": True,
        "selectedOutputs": ["agent_1.content"]
    },
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

const response = await fetch('https://sim.ai/api/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.SIM_API_KEY!
  },
  body: JSON.stringify({
    input: 'Write a long essay',
    stream: true,
    selectedOutputs: ['agent_1.content']
  })
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Asynchronous

For long-running workflows, async mode returns a job ID immediately so you don't need to hold the connection open. Add the X-Execution-Mode: async header to your request. The API returns HTTP 202 with a job ID and status URL. Poll the status URL until the job completes.

curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIM_API_KEY" \
  -H "X-Execution-Mode: async" \
  -d '{ "input": "Process this large dataset" }'

{
  "success": true,
  "async": true,
  "jobId": "run_abc123",
  "executionId": "exec_xyz",
  "message": "Workflow execution queued",
  "statusUrl": "https://sim.ai/api/jobs/run_abc123"
}

curl https://sim.ai/api/jobs/{jobId} \
  -H "x-api-key: $SIM_API_KEY"

{
  "success": true,
  "taskId": "run_abc123",
  "status": "processing",
  "metadata": {
    "createdAt": "2025-09-10T12:00:00.000Z",
    "startedAt": "2025-09-10T12:00:01.000Z"
  },
  "estimatedDuration": 300000
}

{
  "success": true,
  "taskId": "run_abc123",
  "status": "completed",
  "metadata": {
    "createdAt": "2025-09-10T12:00:00.000Z",
    "startedAt": "2025-09-10T12:00:01.000Z",
    "completedAt": "2025-09-10T12:00:05.000Z",
    "duration": 4000
  },
  "output": { "result": "..." }
}

Job Status Values

Poll the statusUrl from the initial response until the status is completed or failed.

Execution Time Limits

If a job exceeds its time limit it is automatically marked as failed.

Job Retention

Completed and failed job results are retained for 24 hours. After that, the status endpoint returns 404. Retrieve and store results on your end if you need them longer.

Capacity Limits

If the execution queue is full, the API returns 503:

{
  "error": "Service temporarily at capacity",
  "retryAfterSeconds": 10
}

API Key Management

Generate and manage API keys in Settings → Sim Keys:

• Create new keys for different applications or environments
• Revoke keys that are no longer needed
• Keys are scoped to your workspace

Rate Limits

API calls are subject to rate limits based on your plan. Rate limit details are returned in response headers (X-RateLimit-*) and in the response body. Use async mode for high-volume or long-running workloads.

For detailed rate limit information and the logs/webhooks API, see External API.