API Overview

The Ctrl AI REST API provides programmatic access to the full platform: run inference queries, manage units and workflows, query audit logs, and administer organizations.

Base URL

# Cloud
https://app.ctrlai.com/api/v1

# Self-hosted
https://your-domain.com/api/v1

Authentication

All API requests require authentication via either:

• API Key — Authorization: Bearer ctrlai_pk_...
• Session Cookie — automatically set when signed in via the web UI

See Authentication for details on creating and managing API keys.

Request Format

• Content-Type: application/json
• All request bodies are JSON
• Query parameters for GET requests (filtering, pagination)

Response Envelope

All responses follow a consistent format:

// Success
{
  "data": { ... },
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {
      "field": "query",
      "issue": "Required"
    }
  }
}

Error Codes

Rate Limits

Rate limit headers are included in every response:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• Retry-After (on 429 responses)

Pagination

List endpoints support pagination via query parameters:

Endpoints