API Overview¶

This page is a route map for Centrali's current HTTP surface. Use the detailed reference pages for exact request and response shapes. Some older docs and internal code still use legacy names, so this overview focuses on the route shapes that are mounted today.

How to Use This Section¶

Use this page when you need to answer one of these questions quickly:

1. Which host should this request go to?
2. Does this endpoint live under /data, /search, /storage, /ai, /realtime, or auth?
3. Is this flow record CRUD, a trigger, a function run, an inbound webhook, or an auth operation?

If you already know the feature area, jump from here to the feature-specific reference page rather than staying on the overview.

Common Starting Points¶

URL Routing¶

Replace {workspace} with your workspace slug.

Naming Notes¶

• Collections is the user-facing term, but older code and routes may still refer to structures.
• Function-related HTTP paths are currently mounted as compute-functions, function-triggers, and function-runs.
• Inbound HTTP triggers and synchronous endpoint triggers sit outside the /data/... prefix:
• POST https://api.centrali.io/workspace/{workspace}/api/v1/http-trigger/{path}
• ANY https://api.centrali.io/workspace/{workspace}/api/v1/endpoints/{path}
• Some collection-adjacent AI routes still resolve through /structures/... internally, so older docs and error messages may still say structure.

Core Data API Paths¶

Assume the Data API base URL:

https://api.centrali.io/data/workspace/{workspace}/api/v1

Other Service Highlights¶

Request Conventions¶

• Use Authorization: Bearer <token> for authenticated requests.
• Use Content-Type: application/json for JSON endpoints.
• Some create endpoints support Idempotency-Key for safe retries, including record creation and webhook subscription creation.
• File uploads use the Storage API and multipart/form-data, not JSON.

Response Conventions¶

Success responses are not fully uniform across the platform yet. Depending on the endpoint, you may see:

• A raw resource object
• { "data": [...], "meta": { ... } } for canonical query and list results
• { "success": true, "data": ... } on some legacy endpoints

Errors use a standardized shape:

{
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "status": 400,
  "timestamp": "2026-04-25T16:00:00.000Z",
  "path": "/data/workspace/acme/api/v1/records/slug/products"
}

Pagination and Filtering¶

For records specifically:

• GET /records/slug/{recordSlug} is the simple list surface
• POST /records/query is the canonical rich-query surface
• Query bodies use the shared QueryDefinition shape with where, text, sort, page, select, and include

Use the endpoint-specific reference page when the exact contract matters.

Rate Limiting¶

Rate limiting is enforced per IP or per publishable key and is not identical across all endpoints.

• The Data API currently defaults to 100 requests per minute per IP
• File uploads use a stricter limit
• Sensitive write flows use a stricter limit
• Publishable-key traffic uses separate per-key read/write limits

On throttled requests, inspect the RateLimit-* headers and the 429 response body.

Quick Examples¶

Create a Collection¶

curl -X POST https://api.centrali.io/data/workspace/acme/api/v1/collections \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Products",
    "recordSlug": "products",
    "properties": [
      {
        "name": "name",
        "type": "string",
        "required": true
      },
      {
        "name": "price",
        "type": "number"
      }
    ]
  }'

Create a Record¶

curl -X POST https://api.centrali.io/data/workspace/acme/api/v1/records/slug/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-create-001" \
  -d '{
    "name": "Widget",
    "price": 99.99,
    "inStock": true
  }'

Query Records¶

curl -X POST "https://api.centrali.io/data/workspace/acme/api/v1/records/query" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "products",
    "where": {
      "data.inStock": { "eq": true }
    },
    "sort": [
      { "field": "createdAt", "direction": "desc" }
    ],
    "page": {
      "limit": 10
    }
  }'

Invoke an HTTP Trigger¶

curl -X POST https://api.centrali.io/workspace/acme/api/v1/http-trigger/inbound/orders \
  -H "Content-Type: application/json" \
  -d '{"source":"partner-system","orderId":"ord_123"}'

Need More Details?¶

• Collections API
• Records API
• Functions API
• Triggers API
• Automations API
• Realtime API
• Webhooks Guide
• Authentication