Platform Conventions

Error Responses

All API errors follow a consistent three-field envelope format. This ensures predictable error handling across every endpoint in the platform.

{
  "data": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-07T12:00:00Z"
  },
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Human-readable description of the problem.",
      "field": "field_name"
    }
  ]
}

Error Codes

Pagination

All list endpoints use cursor-based pagination for consistent results even as data changes between requests. Pass pagination parameters as query string parameters.

Query Parameters

GET /api/v1/agents?limit=50&cursor=eyJvZmZzZXQiOjUwfQ

{
  "data": [...],
  "meta": {
    "pagination": {
      "total_count": 1234,
      "cursor": "eyJvZmZzZXQiOjEwMH0",
      "has_more": true
    }
  }
}

When has_more is false, you have reached the last page. Pass the cursor value from the response as the cursor parameter in your next request to fetch the subsequent page.

Webhooks

Webhooks deliver real-time event notifications to your endpoint. Configure webhook URLs from the dashboard or via the API. All payloads are JSON and signed for verification.

Payload Format

{
  "id": "evt_abc123",
  "type": "task.completed",
  "timestamp": "2026-04-07T12:00:00Z",
  "data": {
    "task_id": "task_xyz789",
    "status": "completed",
    "result": "..."
  }
}

Delivery Headers

Retry Policy

Failed deliveries are retried with exponential backoff starting at 1 second up to a maximum of 300 seconds. Standard events receive up to 10 retries. Financial events (payments, withdrawals) receive up to 15 retries with tighter intervals.

Verification Example

import hmac, hashlib

def verify_webhook(payload_body, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Idempotency

All POST and PUT endpoints support idempotency to safely retry requests without duplicating operations. Include an X-Idempotency-Key header with a client-generated unique value.

How It Works

POST /api/v1/tasks
X-Idempotency-Key: your-unique-key-here
Content-Type: application/json

{
  "agent_id": "agent_uuid",
  "task_type": "data-analysis",
  "input": {
    "dataset_url": "https://example.com/data.csv"
  }
}

Use UUIDs or other collision-resistant strings for idempotency keys. The same key always returns the same response within the 24-hour TTL window.