API Reference

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

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

Rate Limits

Rate limits are applied per API key:

Operation	Limit
Trigger workflow	60 requests/minute
Read operations (get run, list runs)	120 requests/minute
Kill run	30 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

Status	Description
`pending`	Run is queued but hasn’t started
`running`	Workflow is actively executing
`completed`	All nodes finished successfully
`failed`	One or more nodes encountered an error
`cancelled`	Run 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', [])}")

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

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// Trigger workflow
const triggerResponse = await fetch(
  `${BASE_URL}/${WEBHOOK_KEY}/trigger`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({ prompt: "A beautiful landscape" })
  }
);
const run = await triggerResponse.json();
console.log(`Started run: ${run.run_id}`);

// Poll for completion
const pollStatus = async () => {
  while (true) {
    const response = await fetch(
      `${BASE_URL}/${WEBHOOK_KEY}/runs/${run.run_id}`,
      { headers }
    );
    const status = await response.json();

    if (["completed", "failed", "cancelled"].includes(status.status)) {
      return status;
    }
    await new Promise(r => setTimeout(r, 2000));
  }
};

const result = await pollStatus();
console.log("Outputs:", result.outputs);

Overview

Workflows

Runs

Base URL

Authentication

Getting an API Key

Rate Limits

Quick Start

1. Trigger a Workflow

2. Check Run Status

Run Status Values

Error Handling

SDK Examples

​Base URL

​Authentication

​Getting an API Key

​Rate Limits

​Quick Start

​1. Trigger a Workflow

​2. Check Run Status

​Run Status Values

​Error Handling

​SDK Examples

Base URL

Authentication

Getting an API Key

Rate Limits

Quick Start

1. Trigger a Workflow

2. Check Run Status

Run Status Values

Error Handling

SDK Examples