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:

Base URL

Complete Workflow Execution

To execute a workflow and retrieve results:

1. Trigger Workflow

Response:
Save the runId for subsequent requests.

2. Poll for Completion

Poll this endpoint every 2-5 seconds until status is completed or failed:
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:
Response:

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:
Common errors:
  • 401 - Invalid API key
  • 403 - No access to workflow
  • 404 - Workflow or run not found
  • 429 - Rate limit exceeded

Example: Complete Flow

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