Skip to main content

​
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

POST /workflows/{workflowId}/runs/async
Content-Type: application/json
x-origami-key: your-api-key

{
  "nodes": {}
}
Response: 
{
  "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: 
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: 
GET /workflows/{workflowId}/runs/{runId}/async/response
x-origami-key: your-api-key
Response: 
{
  "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: 
{
  "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

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