Getting Started

Base URL

All API requests are made to:

https://www.sim.ai

Quick Start

Get your API key

Go to the Sim dashboard and navigate to Settings → Sim Keys, then click Create. See Authentication for details on key types.

Find your workflow ID

Open a workflow in the Sim editor. The workflow ID is in the URL:

https://www.sim.ai/workspace/{workspaceId}/w/{workflowId}

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.

Make your first request

curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"inputs": {}}'

const response = await fetch(
  `https://www.sim.ai/api/workflows/${workflowId}/execute`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.SIM_API_KEY!,
    },
    body: JSON.stringify({ inputs: {} }),
  }
)

const data = await response.json()
console.log(data.output)

import requests
import os

response = requests.post(
    f"https://www.sim.ai/api/workflows/{workflow_id}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["SIM_API_KEY"],
    },
    json={"inputs": {}},
)

data = response.json()
print(data["output"])

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 passing async: true:

curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"inputs": {}, "async": true}'

This returns immediately with a taskId:

{
  "success": true,
  "taskId": "job_abc123",
  "status": "queued"
}

Poll the Get Job Status endpoint until the status is completed or failed:

curl https://www.sim.ai/api/jobs/{taskId} \
  -H "X-API-Key: YOUR_API_KEY"

Job status transitions follow: queued → processing → completed or failed. The output field is only present when status is completed.

Response Format

Successful responses include an output object with your workflow results and a limits object with your current rate limit and usage status:

{
  "success": true,
  "output": {
    "result": "Hello, world!"
  },
  "limits": {
    "workflowExecutionRateLimit": {
      "sync": {
        "requestsPerMinute": 60,
        "maxBurst": 10,
        "remaining": 59,
        "resetAt": "2025-01-01T00:01:00Z"
      },
      "async": {
        "requestsPerMinute": 30,
        "maxBurst": 5,
        "remaining": 30,
        "resetAt": "2025-01-01T00:01:00Z"
      }
    },
    "usage": {
      "currentPeriodCost": 1.25,
      "limit": 50.00,
      "plan": "pro",
      "isExceeded": false
    }
  }
}

Error Handling

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

{
  "error": "Workflow not found"
}

Status	Meaning	What to do
`400`	Invalid request parameters	Check the `details` array for specific field errors
`401`	Missing or invalid API key	Verify your `X-API-Key` header
`403`	Access denied	Check you have permission for this resource
`404`	Resource not found	Verify the ID exists and belongs to your workspace
`429`	Rate limit exceeded	Wait for the duration in the `Retry-After` header

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

Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions. Every execution response includes a limits object showing your current rate limit status.

When rate limited, the API returns a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

Pagination

List endpoints (workflows, logs, audit logs) use cursor-based pagination:

# First page
curl "https://www.sim.ai/api/v1/logs?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

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

The response includes a nextCursor field. When nextCursor is absent or null, you have reached the last page.