Episodes

POST /v1/episodes

Batch ingest up to 1,000 episodes in a single request.

Request

POST /v1/episodes
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "tenant_id": "my-app",
  "namespace": "engineering",
  "episodes": [
    {
      "type": "message",
      "content": "Standup: completed auth refactor, starting rate limiter.",
      "source": "slack",
      "author": "bob",
      "timestamp": "2026-03-15T09:00:00Z"
    },
    {
      "type": "message",
      "content": "Standup: shipped CockroachDB migration, monitoring for issues.",
      "source": "slack",
      "author": "alice",
      "timestamp": "2026-03-15T09:05:00Z"
    }
  ]
}

| Field | Type | Required | Description | |---|---|---|---| | tenant_id | string | Yes | Tenant identifier | | namespace | string | No | Namespace | | episodes | array | Yes | Array of episode objects (max 1,000) |

Response (201 Created)

{
  "count": 2,
  "event_ids": [44, 45],
  "errors": []
}

If some episodes fail validation:

{
  "count": 1,
  "event_ids": [44],
  "errors": [
    {
      "index": 1,
      "code": "validation_error",
      "message": "Field 'content' is required"
    }
  ]
}

Example

curl -X POST https://api.cortexdb.io/v1/episodes \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "episodes": [
      {"type": "message", "content": "First.", "source": "test"},
      {"type": "message", "content": "Second.", "source": "test"}
    ]
  }'

---

GET /v1/episodes/:id

Retrieve a specific episode by ID.

Request

GET /v1/episodes/ep_a1b2c3d4?tenant_id=my-app
Authorization: Bearer <api-key>

Response (200 OK)

{
  "id": "ep_a1b2c3d4",
  "event_id": 42,
  "type": "decision",
  "content": "Chose CockroachDB for the payments service.",
  "source": "meeting-notes",
  "author": "prashant",
  "timestamp": "2026-03-15T10:00:00Z",
  "metadata": {},
  "entities": [
    {"id": "ent_001", "name": "CockroachDB", "type": "technology"},
    {"id": "ent_002", "name": "payments service", "type": "service"}
  ],
  "status": "active",
  "created_at": "2026-03-15T10:00:01Z"
}

Example

curl https://api.cortexdb.io/v1/episodes/ep_a1b2c3d4 \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app"