sim/apps/docs/content/docs/en/api-reference/getting-started.mdx

---
title: Getting Started
description: Base URL, first API call, response format, error handling, and pagination
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Step, Steps } from 'fumadocs-ui/components/steps'

## Base URL

All API requests are made to:

```
https://www.sim.ai
```

## Quick Start

<Steps>

<Step>
### Get your API key

Go to the Sim platform and navigate to **Settings**, then go to **Sim Keys** and click **Create**. See [Authentication](/api-reference/authentication) for details on key types.
</Step>

<Step>
### 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](/api-reference/workflows/listWorkflows) endpoint to get all workflow IDs in a workspace.
</Step>

<Step>
### Deploy your workflow

A workflow must be deployed before it can be executed via the API. Click the **Deploy** button in the editor toolbar, or use the dashboard to manage deployments.
</Step>

<Step>
### Make your first request

<Tabs items={['curl', 'TypeScript', 'Python']}>
  <Tab value="curl">
    ```bash
    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": {}}'
    ```
  </Tab>
  <Tab value="TypeScript">
    ```typescript
    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)
    ```
  </Tab>
  <Tab value="Python">
    ```python
    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"])
    ```
  </Tab>
</Tabs>
</Step>

</Steps>

## 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`:

```bash
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`:

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

Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:

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

<Callout type="info">
  Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
</Callout>

## Response Format

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

```json
{
  "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:

```json
{
  "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 |

<Callout type="info">
  Use the [Get Usage Limits](/api-reference/usage/getUsageLimits) endpoint to check your current rate limit status and billing usage at any time.
</Callout>

## Rate Limits

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**:

```bash
# 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.