API Reference
Everything you need to invoke Cerebrals, manage customers, configure webhooks, and handle authentication programmatically.
Core Concepts
Sessions & Memory
Pass a session_id to give a Cerebral memory across turns. Same ID = same conversation context. Omit it and each call is stateless. Session memory is per-Cerebral — the same ID on two different Cerebrals is two separate memory stores.
Identity Modes
Set per API key. anonymous — no identity tracked. identified — uses identity if provided, proceeds without it if not. required — rejects calls without a customer_id or identity object with 422.
Authentication
External API calls use X-API-Key header. Platform management (creating keys, reading analytics) uses Authorization: Bearer {JWT}. Never use JWT for Cerebral invocation — always use API keys.
Response Format
Every response follows {"{"} success, data {"}"} on success or {"{"} success, error: {"{"} code, message, requestId {"}"} {"}"} on failure. Always check success first. Use requestId when contacting support.
Cerebrals
The primary invocation endpoint. Send a message to a deployed Cerebral and receive an AI-generated response. Supports persistent sessions, identity injection, and multi-turn conversations. The Cerebral will execute any matching workflows, call actions, and return its response with full execution metadata.
POST https://api.cerebralos.com/v1/cerebrals/:id/message
| idrequired | string (uuid) Cerebral ID e.g. ca67399b-3502-a4f4-4b88-d5725 |
| messagerequired | string The message to send to the Cerebral e.g. "What is the status of order #1234?" |
| session_id | string Session identifier for conversation continuity. Same session_id = same memory context. Omit for stateless calls. e.g. user-abc-123 |
| customer_id | string Your customer identifier. Used for identity injection and memory isolation. e.g. cust_8f2a |
| identity | object Customer identity object. Required if key identity_mode is "required". e.g. { "email": "[email protected]", "name": "Jane Doe" } |
| metadata | object Arbitrary key-value pairs passed through to the execution context. e.g. { "channel": "web", "locale": "en-US" } |
{
"success": true,
"data": {
"message": "Order #1234 is currently in transit. Expected delivery tomorrow 2–6pm.",
"session_id": "user-abc-123",
"execution_id": "exec_9f2b44a1",
"metadata": {
"model": "gpt-4o-mini",
"tokens_used": 312,
"actions_executed": 1,
"latency_ms": 1847,
"sop_matched": "order_status_lookup"
}
}
}
Auth
Authenticate a platform user and receive a JWT token. Use this for platform UI access. For API integrations, use API Keys instead.
POST https://api.cerebralos.com/v1/auth/login
| emailrequired | string User email address |
| passwordrequired | string User password |
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "usr_abc",
"email": "[email protected]",
"tenantId": "ten_xyz"
}
}
}
Register a new tenant account. Sends a verification email on creation.
POST https://api.cerebralos.com/v1/auth/signup
| emailrequired | string Email address |
| passwordrequired | string Password (min 8 chars) |
| name | string Display name |
{
"success": true,
"data": {
"userId": "usr_new",
"message": "Verification email sent"
}
}
API Keys
Create a new API key for programmatic access. The full key is returned exactly once — store it immediately. Only a hashed preview is stored on the server. If you lose it, create a new one.
POST https://api.cerebralos.com/v1/api-keys
| namerequired | string Human-readable key name e.g. Production Shopify Widget |
| cerebral_id | string Lock this key to a specific Cerebral. Calls with this key to other Cerebrals return 403. |
| identity_mode | "anonymous" | "identified" | "required" Controls identity injection behavior. Default: identified. |
| allowed_origins | string[] CORS allowlist. Empty = server-to-server only. e.g. ["https://myapp.com"] |
{
"success": true,
"data": {
"id": "key_9f2b",
"key": "sk_live_4qArx8L2...FULL_KEY_SHOWN_ONCE",
"name": "Production Shopify Widget",
"status": "active",
"createdAt": "2026-02-25T21:44:11Z"
}
}
Returns all API keys for the authenticated tenant. Key values are masked — preview only. Full key is only shown at creation time.
GET https://api.cerebralos.com/v1/api-keys
{
"success": true,
"data": [
{
"id": "key_9f2b",
"key": "sk_4qArx8L2••••••••••••",
"name": "Production Shopify Widget",
"status": "active",
"lastUsedAt": "2026-02-25T18:00:00Z"
}
]
}
Permanently revoke an API key. All in-flight requests using this key fail immediately. This action cannot be undone.
DELETE https://api.cerebralos.com/v1/api-keys/:id
{ "success": true, "data": { "deleted": true } }
Customers
Create a new customer record or upsert by identifier. Customer records are automatically created by the platform when messages arrive — use this for pre-population or manual CRM sync.
POST https://api.cerebralos.com/v1/customers
string Email identifier | |
| phone | string Phone number (E.164 format) e.g. +15551234567 |
| name | string Display name |
| external_id | string Your system ID for this customer e.g. shopify_cust_123 |
| metadata | object Custom attributes e.g. { "plan": "pro" } |
{
"success": true,
"data": {
"id": "cust_8f2a",
"email": "[email protected]",
"name": "Jane Doe",
"createdAt": "2026-02-25T21:44:11Z"
}
}
Retrieve a customer record with all identifiers, tags, and metadata.
GET https://api.cerebralos.com/v1/customers/:id
{
"success": true,
"data": {
"id": "cust_8f2a",
"email": "[email protected]",
"name": "Jane Doe",
"tags": ["vip"],
"metadata": { "plan": "pro" }
}
}
Webhooks
Register a URL to receive platform events. Payloads are signed with HMAC-SHA256 using your webhook secret. Failed deliveries are retried with exponential backoff (1min → 5min → 30min → 2hr → 24hr).
POST https://api.cerebralos.com/v1/webhooks
| urlrequired | string HTTPS endpoint URL e.g. https://myapp.com/webhooks/cerebral |
| eventsrequired | string[] Event types to subscribe to e.g. ["conversation.completed", "escalation.created"] |
| secret | string HMAC signing secret. If omitted, one is generated for you. |
{
"success": true,
"data": {
"id": "wh_5c9d",
"url": "https://myapp.com/webhooks/cerebral",
"events": ["conversation.completed"],
"secret": "whsec_abc123",
"createdAt": "2026-02-25T21:44:11Z"
}
}
Rate Limits
Returns your tenant rate limit configuration and current usage counters. Every API response also includes rate limit state in response headers.
GET https://api.cerebralos.com/v1/rate-limits
{
"success": true,
"data": {
"tenant": {
"requests_per_minute": 60,
"requests_per_hour": 1000,
"requests_per_day": 10000
},
"current": { "minute": 12, "hour": 284, "day": 1847 },
"health": { "budget_state": "ok", "circuit_state": "closed" }
}
}
Reference
Response Headers
Included on every API response
Webhook Events
Subscribe via POST /webhooks
{
"event": "conversation.completed",
"cerebral_id": "ca67399b-...",
"session_id": "user-abc-123",
"customer_id": "cust_8f2a",
"message": "Order shipped!",
"timestamp": "2026-02-25T21:44:11Z"
}
Error Codes
All errors return { success: false, error: { code, message, requestId } }