> ## Documentation Index
> Fetch the complete documentation index at: https://docs.origamiagents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart for AI Agents

> How AI agents can use the Origami API

# Quickstart for AI Agents

This guide is designed for AI agents integrating with Origami workflows programmatically.

## Authentication

All requests require the `x-origami-key` header:

```
x-origami-key: your-api-key
```

## Base URL

```
https://api.origamiagents.com/api/v1
```

## Complete Workflow Execution

To execute a workflow and retrieve results:

### 1. Trigger Workflow

```http theme={null}
POST /workflows/{workflowId}/runs/async
Content-Type: application/json
x-origami-key: your-api-key

{
  "nodes": {}
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "workflowId": "wf_abc123",
    "runId": "run_xyz789",
    "status": "queued"
  }
}
```

Save the `runId` for subsequent requests.

### 2. Poll for Completion

Poll this endpoint every 2-5 seconds until status is `completed` or `failed`:

```http theme={null}
GET /workflows/{workflowId}/runs/{runId}/async/status
x-origami-key: your-api-key
```

**Possible statuses:**

* `queued` - Run is waiting to start
* `running` - Run is in progress
* `completed` - Run finished successfully (proceed to step 3)
* `failed` - Run encountered an error

### 3. Retrieve Results

Once status is `completed`:

```http theme={null}
GET /workflows/{workflowId}/runs/{runId}/async/response
x-origami-key: your-api-key
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "row_1": {
      "output_key": "result value"
    }
  }
}
```

## Rate Limits

* **Trigger**: 50/min global, 30/min per workflow
* **Status Check**: 50/min global, 6/min per run
* **Get Results**: 50/min global

When rate limited (429), wait for the duration specified in the `Retry-After` header.

## Error Handling

All errors return:

```json theme={null}
{
  "success": false,
  "error": "Error message"
}
```

**Common errors:**

* `401` - Invalid API key
* `403` - No access to workflow
* `404` - Workflow or run not found
* `429` - Rate limit exceeded

## Example: Complete Flow

```python theme={null}
import requests
import time

BASE_URL = "https://api.origamiagents.com/api/v1"
HEADERS = {"x-origami-key": "your-api-key"}

# 1. Trigger
response = requests.post(
    f"{BASE_URL}/workflows/{workflow_id}/runs/async",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"nodes": {}}
)
run_id = response.json()["data"]["runId"]

# 2. Poll
while True:
    status_response = requests.get(
        f"{BASE_URL}/workflows/{workflow_id}/runs/{run_id}/async/status",
        headers=HEADERS
    )
    status = status_response.json()["data"]["status"]
    
    if status == "completed":
        break
    elif status == "failed":
        raise Exception("Workflow failed")
    
    time.sleep(2)

# 3. Get results
result_response = requests.get(
    f"{BASE_URL}/workflows/{workflow_id}/runs/{run_id}/async/response",
    headers=HEADERS
)
output = result_response.json()["data"]
```

## Tips for AI Agents

* **Polling frequency**: Start with 2 seconds, increase to 5 seconds after 30 seconds
* **Timeout**: Set a maximum wait time (e.g., 5 minutes) before abandoning
* **Retry logic**: Retry 429 errors after the `Retry-After` duration
* **Parallel execution**: Respect per-workflow rate limits when triggering multiple runs