API Reference
Invoke Cerebrals, trigger Maps, call the Runtime API, 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 uses Authorization: Bearer {JWT}. Runtime API calls use X-API-Key with actions:run or actions:catalog permission. Never use JWT for Cerebral invocation.
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": "jane@example.com", "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": "claude-haiku-4-5",
"tokens_used": 312,
"actions_executed": 1,
"latency_ms": 1847,
"sop_matched": "order_status_lookup"
}
}
}
Maps
Fire a Map directly from your product, your pipeline, or your event stream. Bypasses intent detection entirely — goes straight to the executor. Your payload is injected as trigger_data and is accessible at every step in the Map as {"}trigger_data.field{"}. Governance, idempotency, and audit trail fire automatically.
POST https://api.cerebralos.com/v1/maps/:id/trigger
| idrequired | string Map ID — returned when the Map was created e.g. shopify_order_slack_abc123 |
| payload | object Data injected as trigger_data — accessible in every Map step as {"}trigger_data.key{"}. Can be any shape. e.g. { "order_id": "shop_1156", "customer_email": "jane@example.com" } |
| session_id | string Pass your own idempotency key. Duplicate triggers with the same session_id are safely deduplicated — Map runs once, cached result returned. e.g. "order-1156-trigger-v1" |
{
"success": true,
"data": {
"execution_id": "exec_7x2qp",
"actions_executed": 2,
"governance_status": "approved",
"map_type": "non_cognitive",
"duration_ms": 412
}
}
Runtime API — BYOA
What is the Runtime API?
Bring your own agent. Route its SaaS actions through Cerebral's execution infrastructure. Governance, idempotency fence, credential resolution, and audit trail fire automatically on every call — across 2,800+ integrations.
Runtime API Keys
Create a Runtime key in the dashboard — select "Runtime Key" in the API Keys modal. Runtime keys require actions:catalog permission for the catalog endpoint and actions:run for run and governance endpoints.
Returns every action your agent can call — model-agnostic JSON Schema by default. Add ?format=openai to get OpenAI function-calling blocks ready to drop into a tools array. Every verb includes its risk level and whether your tenant has that provider connected.
GET https://api.cerebralos.com/v1/runtime/actions/catalog
| provider | string Filter by provider slug e.g. shopify |
| domain | string Filter by domain e.g. orders |
| risk_level | string Filter by risk level low | medium | high |
| connected_only | boolean Only return verbs for providers your tenant has connected |
| format | string Pass openai to append OpenAI function-calling tool_definition block per verb openai |
| limit | number Pagination — default 100 |
| offset | number Pagination offset |
{
"success": true,
"data": {
"verbs": [
{
"verb": "shopify:get_order",
"provider": "shopify",
"domain": "orders",
"description": "Retrieve a single order by ID",
"risk_level": "low",
"operation_type": "read",
"connected": true,
"schema": {
"type": "object",
"properties": {
"order_id": { "type": "string", "description": "The Shopify order ID" }
},
"required": ["order_id"]
}
}
],
"total": 17578,
"providers_connected": ["shopify", "stripe", "klaviyo"],
"pagination": { "limit": 100, "offset": 0, "has_more": true }
}
}
// With ?format=openai — adds tool_definition per verb:
// "tool_definition": {
// "type": "function",
// "function": {
// "name": "shopify__get_order", ← double underscore (OpenAI constraint)
// "description": "...",
// "parameters": { ... }
// }
// }
Execute any verb in the catalog. Governance checks the verb against your policy before anything executes. Credentials are resolved from the vault — your agent never handles secrets. The idempotency fence prevents duplicate execution. Every call is logged. Pass metadata: {"{"} dryRun: true {"}"} to intercept writes without executing them.
POST https://api.cerebralos.com/v1/runtime/actions/run
| verbrequired | string The action to execute — format: provider:verb_name e.g. shopify:get_order |
| argsrequired | object Verb arguments — validated against the verb schema from the catalog |
| execution_id | string Your unique execution ID — powers the idempotency fence. Always pass if you want safe retries. Duplicate calls with the same execution_id return the cached result without re-executing. e.g. "agent-session-abc-action-1" |
| session_id | string Groups calls into a logical session for the audit log |
| metadata | object Pass-through stored in action_runs. Use dryRun: true to intercept writes without executing. e.g. { "agent": "my-langchain-agent", "dryRun": true } |
// Success
{
"success": true,
"data": {
"result": { ... },
"normalized": { ... },
"execution_id": "exec_abc123",
"fence_status": "executed",
"governance_status": "approved",
"provider": "shopify",
"verb": "shopify:get_order",
"duration_ms": 312
}
}
// Idempotency fence hit — duplicate caught, cached result returned
{
"success": true,
"data": {
"result": { ... },
"fence_status": "cached",
"message": "Duplicate execution detected — returning cached result"
}
}
// Governance blocked
{
"success": false,
"error": {
"code": "GOVERNANCE_BLOCKED",
"message": "Action blocked by tenant policy: high-risk write requires approval",
"approval_id": "appr_xyz789"
}
}
Check whether an action would be approved, blocked, or require human escalation — before your agent commits to executing it. Nothing executes. Returns the governance decision with the policy that matched and the risk level of the verb.
POST https://api.cerebralos.com/v1/runtime/governance/evaluate
| verbrequired | string The verb to evaluate e.g. shopify:cancel_order |
| args | object Verb arguments — used to evaluate condition-based policies (e.g. refund amount > $100) |
{
"success": true,
"data": {
"decision": "pending_approval",
"reason": "High-risk write on shopify requires approval",
"risk_level": "high",
"operation_type": "write",
"provider": "shopify",
"verb": "cancel_order",
"approval_required": true,
"policy_name": "Shopify Write Gate"
}
}
// decision values: "allow" | "block" | "pending_approval"
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": "ben@10e9.com", "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. The full key is returned exactly once — store it immediately. Only a hashed preview is stored on the server. Two key types: Cerebral keys (cerebrals:message permission) and Runtime keys (actions:run, actions:catalog permissions).
POST https://api.cerebralos.com/v1/api-keys
| namerequired | string Human-readable key name e.g. Production Runtime Key |
| permissions | string[] Permissions for this key. Defaults to ["cerebrals:message"] if omitted. For Runtime keys pass ["actions:run","actions:catalog"]. |
| cerebral_id | string Lock this key to a specific Cerebral. Calls with this key to other Cerebrals return 403. Not used for Runtime keys. |
| identity_mode | string anonymous | identified | required. Controls identity injection. Default: identified. Not used for Runtime keys. |
| allowed_origins | string[] CORS allowlist. Empty = server-to-server only. |
{
"success": true,
"data": {
"id": "key_9f2b",
"key": "sk_live_4qArx8L2...FULL_KEY_SHOWN_ONCE",
"name": "Production Runtime Key",
"status": "active",
"createdAt": "2026-04-07T14:32:01Z"
}
}
Returns all API keys for the authenticated tenant. Key values are masked — preview only.
GET https://api.cerebralos.com/v1/api-keys
{
"success": true,
"data": [
{ "id": "key_9f2b", "key": "sk_4qArx8L2••••••••••••", "name": "Production Runtime Key", "status": "active", "lastUsedAt": "2026-04-07T14:00:00Z" }
]
}
Permanently revoke an API key. All in-flight requests using this key fail immediately. 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": "jane@example.com", "name": "Jane Doe", "createdAt": "2026-04-07T14:32:01Z" } }
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": "jane@example.com", "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-04-07T14:32:01Z"
}
}
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-04-07T14:32:01Z"
}
Error Codes
All errors return { success: false, error: { code, message, requestId } }