API Reference

All endpoints require an X-API-Key header unless noted otherwise.

Context Layer

POST/api/context

Store a context object. Embeddings are auto-generated if OPENAI_API_KEY is configured.

Request Body
{
  "taskId": "task_001",           // required
  "entityId": "customer_123",     // required
  "agentId": "chatbot",           // required
  "input": "User question",       // required
  "output": "Agent response",     // required
  "embedding": [0.1, ...],        // optional, 1536-dim
  "metadata": { "key": "value" }  // optional
}
Response
{ "id": "uuid", "taskId": "...", "entityId": "...", ... }  // 201 Created
GET/api/context/:id

Retrieve a specific context object by ID.

Response
{ "id": "uuid", "taskId": "...", "entityId": "...", ... }  // 200 OK
{ "error": "Context not found" }  // 404
GET/api/context/search

Search context objects by text query (semantic), raw embedding, or filters.

Query Parameters
query         // text query (auto-embedded for semantic search)
embedding     // raw 1536-dim JSON array (alternative to query)
entityId      // filter by entity
agentId       // filter by agent
limit         // max results (1-100, default 10)
Response
[{ "id": "...", "similarity": 0.87, ... }]  // 200 OK
GET/api/context/inject

Get formatted context block ready for prompt injection.

Query Parameters
query           // required, text query
entityId        // filter by entity
agentId         // filter by agent
limit           // max results (default 5)
minSimilarity   // threshold (default 0.3)
Response
{
  "context": "--- Prior Context ---\n[Context 1 from chatbot (relevance: 87%)]\n...",
  "hasContext": true
}

Coordination Layer

POST/api/tasks/claim

Claim a task for an entity. Returns 409 if another agent already has an active task for this entity.

Request Body
{
  "entityId": "customer_123",  // required
  "agentId": "chatbot",        // required
  "input": "Handle request",   // required
  "metadata": {}               // optional
}
Response
{ "id": "uuid", "status": "claimed", ... }  // 201 Created
{ "error": "Task conflict", "activeTask": { ... } }  // 409 Conflict
GET/api/tasks/active

List all active (claimed or in_progress) tasks.

Query Parameters
entityId   // optional filter
Response
[{ "id": "...", "status": "claimed", "agentId": "...", ... }]
PATCH/api/tasks/:id/complete

Mark a task as completed with output.

Request Body
{
  "output": "Task result",  // required
  "metadata": {}             // optional, merged with existing
}
Response
{ "id": "...", "status": "completed", "completedAt": "...", ... }
POST/api/tasks/:id/handoff

Hand off a task to another agent. Original task is marked as handed_off and a new task is created for the target agent.

Request Body
{
  "targetAgentId": "escalation-handler",  // required
  "context": "Handoff context...",         // required
  "metadata": {}                           // optional
}
Response
{
  "handedOff": { "id": "...", "status": "handed_off", ... },
  "newTask": { "id": "...", "status": "claimed", "agentId": "escalation-handler", ... }
}  // 201 Created

Learning Layer

POST/api/workflows

Log a complete workflow trace. Embeddings are auto-generated from steps.

Request Body
{
  "entityId": "customer_123",
  "steps": [
    {
      "agentId": "chatbot",
      "action": "process_message",
      "input": "Customer complaint",
      "output": "Identified issue",
      "timestamp": "2025-04-05T10:00:00Z"
    }
  ],
  "outcome": "success",    // "success" | "failure" | "partial"
  "duration": 900,          // optional, milliseconds
  "metadata": {}            // optional
}
Response
{ "id": "uuid", "entityId": "...", "outcome": "success", ... }  // 201 Created
GET/api/workflows/:id

Retrieve a specific workflow trace.

Response
{ "id": "uuid", "steps": [...], "outcome": "success", ... }
GET/api/workflows/similar

Find similar past workflows using semantic search.

Query Parameters
query      // required, text query
entityId   // optional filter
outcome    // optional filter ("success" | "failure" | "partial")
limit      // max results (1-50, default 5)
Response
[{ "id": "...", "similarity": 0.82, "outcome": "success", "steps": [...], ... }]

Authentication

POST/api/auth/signupNo auth required

Create a new organization and get your first API key. The key is only shown once.

Request Body
{
  "name": "My Company",        // required
  "slug": "my-company"         // required, lowercase alphanumeric + hyphens
}
Response
{
  "organization": { "id": "...", "name": "My Company", "slug": "my-company" },
  "apiKey": { "id": "...", "key": "ck_live_...", "prefix": "ck_live_abc1", "label": "default" }
}  // 201 Created
POST/api/auth/keys

Create an additional API key for your organization.

Request Body
{ "label": "production" }  // optional, default "default"
Response
{ "id": "...", "key": "ck_live_...", "prefix": "...", "label": "production" }  // 201
GET/api/auth/keys

List all API keys for your organization (prefix only, not the full key).

Response
[{ "id": "...", "prefix": "ck_live_abc1", "label": "default", "lastUsedAt": "...", "createdAt": "..." }]