HTTP API Reference

All endpoints are under /cortex and return JSON. Authentication and tenant resolution depend on your middleware configuration. Set X-Tenant-ID and X-App-ID headers for multi-tenant deployments.

Agents (7 routes)

POST /cortex/agents

Create an agent configuration.

Request

{
  "name": "support-agent",
  "description": "Customer support agent",
  "system_prompt": "You are a helpful support agent.",
  "model": "gpt-4o",
  "tools": ["lookup_order", "create_ticket"],
  "max_steps": 15,
  "max_tokens": 4096,
  "temperature": 0.7,
  "reasoning_loop": "react",
  "persona_ref": "helpful-agent",
  "inline_skills": ["customer-support"],
  "inline_traits": ["empathy"],
  "inline_behaviors": ["auto-escalate"],
  "guardrails": {},
  "metadata": {}
}

Response 201 Created — Agent object with generated id (e.g. agt_01h455...).

GET /cortex/agents

List all agents for the current tenant/app.

Query parameters

Response 200 OK — Array of Agent objects.

GET /cortex/agents/:name

Get an agent by name.

Response 200 OK — Agent object.

Error 404 Not Found if agent does not exist.

PUT /cortex/agents/:name

Update an agent configuration. Only provided fields are updated.

Request — Same shape as create, all fields optional except name (path).

Response 200 OK — Updated Agent object.

DELETE /cortex/agents/:name

Delete an agent configuration.

Response 204 No Content

POST /cortex/agents/:name/run

Execute an agent synchronously. Returns when the run completes.

Request

{
  "input": "I want to return order #12345"
}

Response 200 OK

{
  "run_id": "arun_01h455...",
  "state": "completed",
  "output": "I'd be happy to help with your return...",
  "step_count": 3,
  "tokens_used": 1240
}

POST /cortex/agents/:name/stream

Execute an agent with Server-Sent Events (SSE) streaming.

Request — Same as /run.

Response 200 OK with Content-Type: text/event-stream.

Runs (3 routes)

GET /cortex/agents/:name/runs

List runs for a specific agent.

Query parameters

Response 200 OK — Array of Run objects.

GET /cortex/runs/:id

Get a specific run by ID.

Response 200 OK

{
  "id": "arun_01h455...",
  "agent_id": "agt_01h455...",
  "tenant_id": "acme-corp",
  "state": "completed",
  "input": "I want to return order #12345",
  "output": "I'd be happy to help...",
  "error": "",
  "step_count": 3,
  "tokens_used": 1240,
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z",
  "persona_ref": "helpful-agent",
  "metadata": {}
}

POST /cortex/runs/:id/cancel

Cancel a running run. Sets state to cancelled.

Response 200 OK

Skills (5 routes)

POST /cortex/skills

Create a skill.

Request

{
  "name": "customer-support",
  "description": "Handle customer inquiries",
  "tools": [
    {"tool_name": "lookup_order", "mastery": "expert", "guidance": "Verify order ID format"},
    {"tool_name": "create_ticket", "mastery": "proficient"}
  ],
  "knowledge": [
    {"source": "policies://return-policy", "inject_mode": "always", "priority": 1}
  ],
  "system_prompt_fragment": "You are an expert support agent.",
  "dependencies": [],
  "default_proficiency": "proficient",
  "metadata": {}
}

Response 201 Created — Skill object with generated id (e.g. skl_01h455...).

GET /cortex/skills

List all skills.

Query parameters — limit, offset.

Response 200 OK — Array of Skill objects.

GET /cortex/skills/:name

Get a skill by name.

Response 200 OK — Skill object.

PUT /cortex/skills/:name

Update a skill.

Response 200 OK — Updated Skill object.

DELETE /cortex/skills/:name

Delete a skill.

Response 204 No Content

Traits (5 routes)

POST /cortex/traits

Create a trait.

Request

{
  "name": "empathy",
  "description": "Emotional awareness and patience",
  "category": "emotional",
  "dimensions": [
    {"name": "emotional-awareness", "low_label": "detached", "high_label": "empathetic", "value": 0.85}
  ],
  "influences": [
    {"target": "tone", "value": "warm", "weight": 0.8}
  ],
  "metadata": {}
}

Response 201 Created — Trait object with generated id (e.g. trt_01h455...).

GET /cortex/traits

List all traits.

Query parameters — limit, offset, category (filter by trait category).

Response 200 OK — Array of Trait objects.

GET /cortex/traits/:name

Get a trait by name.

Response 200 OK — Trait object.

PUT /cortex/traits/:name

Update a trait.

Response 200 OK — Updated Trait object.

DELETE /cortex/traits/:name

Delete a trait.

Response 204 No Content

Behaviors (5 routes)

POST /cortex/behaviors

Create a behavior.

Request

{
  "name": "auto-escalate",
  "description": "Escalate on negative sentiment",
  "priority": 10,
  "triggers": [
    {"type": "sentiment_below", "pattern": "0.3"},
    {"type": "keyword_match", "pattern": "speak to manager"}
  ],
  "actions": [
    {"type": "modify_tone", "target": "tone", "value": "extra empathetic"},
    {"type": "inject_prompt", "value": "Acknowledge frustration first."}
  ],
  "requires_skill": "",
  "requires_trait": "",
  "metadata": {}
}

Response 201 Created — Behavior object with generated id (e.g. bhv_01h455...).

GET /cortex/behaviors

List all behaviors.

Query parameters — limit, offset.

Response 200 OK — Array of Behavior objects.

GET /cortex/behaviors/:name

Get a behavior by name.

Response 200 OK — Behavior object.

PUT /cortex/behaviors/:name

Update a behavior.

Response 200 OK — Updated Behavior object.

DELETE /cortex/behaviors/:name

Delete a behavior.

Response 204 No Content

Personas (5 routes)

POST /cortex/personas

Create a persona.

Request

{
  "name": "helpful-agent",
  "description": "Warm customer support persona",
  "identity": "I am a support specialist who genuinely cares.",
  "skills": [
    {"skill_name": "customer-support", "proficiency": "expert"}
  ],
  "traits": [
    {"trait_name": "empathy", "dimension_values": {"emotional-awareness": 0.85}}
  ],
  "behaviors": ["auto-escalate"],
  "cognitive_style": {},
  "communication_style": {},
  "perception": {},
  "metadata": {}
}

Response 201 Created — Persona object with generated id (e.g. prs_01h455...).

GET /cortex/personas

List all personas.

Query parameters — limit, offset.

Response 200 OK — Array of Persona objects.

GET /cortex/personas/:name

Get a persona by name.

Response 200 OK — Persona object.

PUT /cortex/personas/:name

Update a persona.

Response 200 OK — Updated Persona object.

DELETE /cortex/personas/:name

Delete a persona.

Response 204 No Content

Checkpoints (2 routes)

GET /cortex/checkpoints

List pending checkpoints (runs paused for human approval).

Query parameters — limit, offset.

Response 200 OK — Array of Checkpoint objects.

POST /cortex/checkpoints/:id/resolve

Resolve a checkpoint.

Request

{
  "decision": "approved",
  "decided_by": "admin@acme.com"
}

Response 200 OK

Memory (2 routes)

GET /cortex/agents/:name/conversation

Get conversation history for an agent.

Query parameters

Response 200 OK — Array of Message objects.

DELETE /cortex/agents/:name/conversation

Clear conversation history for an agent.

Response 204 No Content

Tools (2 routes)

GET /cortex/tools

List all registered tools.

Response 200 OK — Array of tool descriptors.

GET /cortex/tools/:name/schema

Get the JSON Schema for a specific tool.

Response 200 OK — JSON Schema object.

Error format

All error responses use a consistent JSON envelope:

{
  "error": "human-readable message",
  "code": "ERROR_CODE"
}

Route summary