---
title: HTTP API Reference
description: Complete reference for all 36 Cortex REST endpoints — agents, runs, skills, traits, behaviors, personas, checkpoints, memory, and tools.
---

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**

```json
{
  "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**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | int | 50 | Max results |
| `offset` | int | 0 | Pagination offset |

**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**

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

**Response** `200 OK`

```json
{
  "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**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | int | 50 | Max results |
| `offset` | int | 0 | Pagination offset |

**Response** `200 OK` — Array of Run objects.

---

### `GET /cortex/runs/:id`

Get a specific run by ID.

**Response** `200 OK`

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | int | 50 | Max messages to return |

**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:

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

| HTTP status | `code` | Cause |
|-------------|--------|-------|
| `400` | `BAD_REQUEST` | Missing required field, invalid input |
| `404` | `NOT_FOUND` | Entity not found for tenant |
| `409` | `ALREADY_EXISTS` | Entity with that name already exists |
| `500` | `INTERNAL_ERROR` | Store or engine failure |

## Route summary

| Resource | Routes | Methods |
|----------|--------|---------|
| Agents | 7 | POST, GET, GET, PUT, DELETE, POST (run), POST (stream) |
| Runs | 3 | GET (list), GET (by ID), POST (cancel) |
| Skills | 5 | POST, GET, GET, PUT, DELETE |
| Traits | 5 | POST, GET, GET, PUT, DELETE |
| Behaviors | 5 | POST, GET, GET, PUT, DELETE |
| Personas | 5 | POST, GET, GET, PUT, DELETE |
| Checkpoints | 2 | GET (list), POST (resolve) |
| Memory | 2 | GET, DELETE |
| Tools | 2 | GET (list), GET (schema) |
| **Total** | **36** | |