---
title: "Start Session"
method: POST
path: "/sessions"
tags: ["sessions"]
---

# Start Session

`POST /sessions`

## Request

- Base URL: `https://api.nicheangle.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.nicheangle.com/sessions`
- Auth: none declared

## Headers

- `authorization` string, nullable

## Request body

- StartSessionRequest
  - `niche_input` string, required
  - `target_outputs` string[], nullable
  - `products_ordered` boolean, nullable
  - `target_platforms` string[]
  - `voice_context` VoiceContext
    - `tone_words` string
    - `audience_context` string
    - `avoid` string
  - `brand_id` string, nullable
  - `image_kind` string, nullable

## Response `201`

Successful Response

- SessionResponse
  - `id` string, uuid, required
  - `status` 'initializing' | 'expanding_niche' | 'planning_search' | 'discovering_signals' | 'clustering' | 'ranking' | 'cp1_awaiting_story' | 'extracting_signal' | 'generating_angles' | 'cp2_awaiting_angle' | 'applying_voice' | 'generating_content' | 'rendering_static' | 'rendering_video' | 'cp3_awaiting_review' | 'awaiting_forge' | 'complete' | 'failed', required
  - `niche_input` string, required
  - `target_platforms` string[], required
  - `created_at` string, date-time, required
  - `chat_thread_id` string, uuid, nullable
  - `updated_at` string, date-time, required
  - `filed_at` string, date-time, nullable
  - `reel_render` object, nullable
  - `iron` object, nullable
  - `niche_profile` object, nullable
  - `selected_story` object, nullable
  - `selected_story_signals` object[]
  - `selected_story_id` string, nullable
  - `selected_angle_id` string, nullable
  - `angles` object[]
  - `ranked_stories` object[]
  - `news_peg` object, nullable
  - `recommended_story_id` string, nullable
  - `recommendation_reason` string, nullable
  - `pool_thin_note` string, nullable
  - `pool_narrow_note` string, nullable
  - `credits_spent` integer, nullable
  - `error_message` string, nullable
  - `outcome` string, required: Finer ending than raw status (N1): complete / expired / interrupted / cancelled / failed / running. Lets the archive show a walk-away (a slate WAS produced) distinctly from a real error, instead of a blanket 'Failed'.

## Other responses

- `422`: Validation Error

---

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