---
title: "Create Episode"
method: POST
path: "/v1/episodes"
tags: ["episodes"]
---

# Create Episode

`POST /v1/episodes`

## Request

- Base URL: `https://api.heirmos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.heirmos.com/v1/episodes`
- Auth: HTTP bearer

## Request body

- EpisodeCreate: POST /v1/episodes request body — SPEC §9.1.
  - `raw_text` string, required
  - `kind` 'conversation' | 'note' | 'document' | 'event' | 'task' | 'other'
  - `title` string, nullable
  - `participants` string[], nullable
  - `project_hint` string, nullable
  - `source_kind` string, nullable
  - `source_id` string, nullable
  - `occurred_at` string, date-time, nullable

## Response `201`

Successful Response

- EpisodeProcessResult: POST /v1/episodes response — the stored episode + pipeline outcomes.
  - `episode` EpisodeRead, required: Episode summary surfaced on ingest + GET.
    - `id` string, uuid, required
    - `kind` string, required
    - `title` string, nullable
    - `project_hint` string, nullable
    - `status` string, required
    - `created_at` string, date-time, required
    - `processed_at` string, date-time, nullable
    - `occurred_at` string, date-time, nullable
  - `outcomes` CandidateOutcome[], required
    - `action` 'created' | 'needs_review' | 'conflicting' | 'skipped_duplicate' | 'dropped_unworthy' | 'dropped_low_importance', required
    - `statement` string, required
    - `path` string, nullable
    - `memory_id` string, uuid, nullable
    - `type` string, nullable
    - `scope` string, nullable
    - `status` string, nullable
    - `confidence` number, nullable
    - `importance` number, nullable
    - `relation` string, nullable
    - `suggested_path` string, nullable
    - `reason` string
  - `created` integer
  - `skipped` integer
  - `dropped` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/heirmos/apis/heirmos-api.md) · [All operations](https://skmtc.dev/heirmos/apis/heirmos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heirmos/apis/heirmos-api/revisions/ed490b1866e7?raw)