Skip to content

API Overview

Base URLs

Centrali services are accessible through these base URLs:

Service Base URL
Data API https://api.centrali.io/data/workspace/{workspace}/api/v1
Auth/IAM https://auth.centrali.io/workspace/{workspace}/api/v1
Storage https://api.centrali.io/storage/workspace/{workspace}/api/v1
Notification https://api.centrali.io/notification/workspace/{workspace}/api/v1
Workspace Management https://api.centrali.io/workspace/api/v1

Replace {workspace} with your workspace identifier.

Authentication

All API requests require authentication using Bearer tokens:

Authorization: Bearer YOUR_API_KEY

Core Endpoints

Data Service

The Data Service handles all your structures, records, and compute functions.

Method Endpoint Description
Structures
GET /structures List all structures
POST /structures Create a new structure
GET /structures/{id} Get structure details
PUT /structures/{id} Update structure
DELETE /structures/{id} Delete structure
Records
GET /records List records
POST /records Create a record
GET /records/{id} Get a record
PATCH /records/{id} Update a record
DELETE /records/{id} Delete a record
POST /records/bulk Bulk operations
Functions
GET /functions List functions
POST /functions Create function
GET /functions/{id} Get function
PUT /functions/{id} Update function
POST /functions/{id}/execute Execute function
Triggers
GET /triggers List triggers
POST /triggers Create trigger
GET /triggers/{id} Get trigger
PUT /triggers/{id} Update trigger
DELETE /triggers/{id} Delete trigger
Query
POST /query Execute CQL query
Webhooks
GET /webhooks List webhooks
POST /webhooks Create webhook
DELETE /webhooks/{id} Delete webhook

Storage Service

Method Endpoint Description
POST /upload Upload a file
GET /files/{id} Download a file
DELETE /files/{id} Delete a file
GET /files List files

Notification Service

Method Endpoint Description
POST /email Send email
POST /sms Send SMS
GET /templates List templates
POST /templates Create template

Request Format

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

All POST/PUT/PATCH requests use JSON:

{
  "field": "value",
  "nested": {
    "data": "example"
  }
}

Response Format

Success Response

{
  "id": "rec_123",
  "data": {
    "field": "value"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' is required",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

HTTP Status Codes

Code Meaning
200 Success
201 Created
204 No Content (deleted)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
429 Rate Limited
500 Internal Server Error

Rate Limits

Operation Type Limit Window
Read operations 5000 Per minute
Write operations 1000 Per minute
Bulk operations 100 Per minute
Function executions 500 Per minute

Exceeded limits return HTTP 429 with a Retry-After header.

Pagination

List endpoints support pagination:

GET /records?limit=20&offset=40

Response includes pagination info:

{
  "results": [...],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 150,
    "hasMore": true
  }
}

Filtering

Use query parameters for filtering:

# Simple filter
GET /records?status=active

# Multiple filters (AND)
GET /records?status=active&category=electronics

# Range filter
GET /records?price_min=10&price_max=100

Sorting

Use the sort parameter:

# Ascending
GET /records?sort=createdAt

# Descending
GET /records?sort=-createdAt

# Multiple fields
GET /records?sort=-priority,createdAt

Quick Examples

Create a Structure

curl -X POST https://api.centrali.io/data/workspace/acme/api/v1/structures \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product",
    "fields": {
      "name": {"type": "text", "required": true},
      "price": {"type": "number", "required": true}
    }
  }'

Create a Record

curl -X POST https://api.centrali.io/data/workspace/acme/api/v1/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "structureId": "str_abc123",
    "data": {
      "name": "Widget",
      "price": 99.99
    }
  }'

Query Records

curl -X POST https://api.centrali.io/data/workspace/acme/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "FROM Product WHERE price > 50 ORDER BY createdAt DESC LIMIT 10"
  }'

Need More Details?