Skip to main content
The Cordage Webhook API allows you to programmatically trigger workflows, monitor execution status, and retrieve generated outputs. Use this API to integrate AI workflows into external applications, automation pipelines, or custom tools.

​
Base URL

All API requests should be made to: 
https://api.trycordage.com/api/webhooks

​
Authentication

All endpoints require authentication using an API key. Include your API key in the Authorization header: 
Authorization: Bearer cordage_xxxxxxxxxxxx
Keep your API keys secure. Never expose them in client-side code or public repositories.

​
Getting an API Key

  1. Navigate to Workspace Settings in the Cordage app
  2. Click API Keys in the sidebar
  3. Click Create API Key
  4. Copy and securely store your key (it won’t be shown again)

​
Rate Limits

Rate limits are applied per API key:
OperationLimit
Trigger workflow60 requests/minute
Read operations (get run, list runs)120 requests/minute
Kill run30 requests/minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 45

​
Quick Start

​
1. Trigger a Workflow

curl -X POST https://api.trycordage.com/api/webhooks/YOUR_WEBHOOK_KEY/trigger \
  -H "Authorization: Bearer cordage_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A beautiful sunset over mountains"}'
Response: 
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "Workflow started",
  "node_count": 5
}

​
2. Check Run Status

curl https://api.trycordage.com/api/webhooks/YOUR_WEBHOOK_KEY/runs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer cordage_xxxxxxxxxxxx"
Response when completed: 
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:15Z",
  "outputs": [
    "https://storage.trycordage.com/outputs/image_001.png"
  ]
}

​
Run Status Values

StatusDescription
pendingRun is queued but hasn’t started
runningWorkflow is actively executing
completedAll nodes finished successfully
failedOne or more nodes encountered an error
cancelledRun was manually cancelled

​
Error Handling

All errors return a JSON object with an error field: 
{
  "error": "Webhook not found"
}
For rate limit errors, a retry_after field indicates when to retry: 
{
  "error": "Rate limit exceeded.",
  "retry_after": 30
}

​
SDK Examples

import requests

API_KEY = "cordage_xxxxxxxxxxxx"
WEBHOOK_KEY = "your_webhook_key"
BASE_URL = "https://api.trycordage.com/api/webhooks"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Trigger workflow
response = requests.post(
    f"{BASE_URL}/{WEBHOOK_KEY}/trigger",
    headers=headers,
    json={"prompt": "A beautiful landscape"}
)
run = response.json()
print(f"Started run: {run['run_id']}")

# Poll for completion
import time
while True:
    status = requests.get(
        f"{BASE_URL}/{WEBHOOK_KEY}/runs/{run['run_id']}",
        headers=headers
    ).json()

    if status["status"] in ["completed", "failed", "cancelled"]:
        break
    time.sleep(2)

print(f"Outputs: {status.get('outputs', [])}")