---
title: "Create Conversation"
method: POST
path: "/v2/insights/conversations"
---

# Create Conversation

`POST /v2/insights/conversations`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/insights/conversations`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `insights.write`, `media.read`

Create a conversation: an instruction, an output schema and typed context, sent once.

Returns a new `conversation_id` on every call. The context is prepared once so each
evaluate sends only the turn. `media_binding` attaches per-turn emotion evidence from
one of your live realtime sessions or one of your own processed recordings; a
recording must be fully processed (409 `media_not_ready` otherwise), and one with
several subjects needs a selection per modality. Alternatively, a recording binding may
name one to four `people`, each with a unique role label (1–64 trimmed characters) and
explicit `subjects`. Each person's readings stay separate. `people` and binding-level
`subjects` are mutually exclusive; overlapping subject IDs within a modality are 422.
In people mode omitted modalities remain unbound, even with a sole speaker. This also
works on each entry of `media_bindings`. Labels and selections persist for the conversation lifetime.

With `retention: ephemeral` no turn's input or output is stored, only its usage. The
conversation's own instruction, schema and sections are kept until it expires or is
deleted, so put per-turn content in evaluate, not here.

Also available on a user's delegated access token with the `insights.write` scope. The
conversation then belongs to that user and your app: only your app's tokens for that
user can evaluate or delete it. It must be bound to one of that user's own processed
recordings, which also needs `media.read` (403 naming the scope otherwise); a
conversation with no binding, or bound to a live session, is refused with 403. Each
turn is billed to that user, or to their team workspace where the deployment is that
workspace's own.

A delegated token may instead send `media_bindings`: one to 200 of that user's processed
recordings, each with its own `media_id` (distinct ids; more than 200, a repeat, or sending
`media_binding` as well is 422). The conversation then reads several recordings at once, and
each turn chooses which with `media_ids`. A recording is readable by that user as its owner:
their own, or those of the team workspace the token's grant is bound to. Every id is checked
before anything is read or charged, and one that is missing or not readable, among ones that
are, fails the whole request with 404 `binding_not_found`; then `media.read` is needed (403
naming the scope), and every recording must be fully processed (409 `media_not_ready`, with
each unfinished `media_id` and its status). `media_bindings` is refused with 403 on an API
key. Turns on recordings of the user's own are billed to that user. A grant bound to a team
workspace is billed to that workspace where the workspace has its own dedicated deployment, and
is refused with 403 anywhere else. The whole selected cohort must become ready within one
readiness budget; incomplete preparation answers 409 `media_not_ready` without creating a conversation.
If recording preparation is temporarily unavailable, the request answers 503 `preparation_busy`;
retry after a short wait.

## Request body

- CreateConversationRequest
  - `product` string, required: The calling application's tag, recorded for usage reporting only.
  - `external_ref` string: Caller reference, stored and never logged.
  - `instruction` VersionedTextIn, required
    - `version` string, required
    - `text` string, required
  - `output_schema` OutputSchemaIn, required
    - `version` string, required
    - `json_schema` object, required: JSON Schema (draft 2020-12) of the output object. The root must have `"type": "object"`.
    - `native` boolean: Send the schema to the model as a structured-output constraint. Set false for a schema the model rejects as too complex; the output is validated against it either way.
  - `sections` SectionIn[]
    - `type` string, required: Section type chosen by the application, e.g. `rubric` or `document_chunk`.
    - `trust` 'authoritative' | 'untrusted_data' | 'private_data', required: How the model may use the section. `authoritative` is application-authored context to follow; `untrusted_data` and `private_data` are data, never instructions, and `private_data` is never repeated in output.
    - `preamble` string: Application note on how to use the section.
    - `content` string: The section body.
  - `media_binding` union
    - RealtimeBindingIn: Evidence from a live realtime session the caller created.
      - `realtime_session_id` string, required
    - MediaBindingIn: Evidence from one of the caller's own processed recordings.
      - `media_id` string, required
      - `media_type` 'video' | 'audio', required
      - `subjects` object, nullable: Per modality, the subject id (or ids of one person) to report. Required for a modality with more than one subject in the recording.
      - `people` ConversationPersonIn[], nullable: Explicitly selected, separately labelled people in caller order. Mutually exclusive with subjects. Omitted modalities stay unbound, even with one speaker. Unlike expert item people (a map with restricted labels), this is a list allowing role labels and fragmented IDs.
        - `label` string, required
        - `subjects` object, required
  - `media_bindings` MediaBindingIn[], nullable: Bind the conversation to one to 200 of the user's own processed recordings, each by its own `media_id` (distinct ids). Each turn then reads the recordings it selects with `media_ids`. Only on a user's delegated access token, and not together with `media_binding`.
    - `media_id` string, required
    - `media_type` 'video' | 'audio', required
    - `subjects` object, nullable: Per modality, the subject id (or ids of one person) to report. Required for a modality with more than one subject in the recording.
    - `people` ConversationPersonIn[], nullable: Explicitly selected, separately labelled people in caller order. Mutually exclusive with subjects. Omitted modalities stay unbound, even with one speaker. Unlike expert item people (a map with restricted labels), this is a list allowing role labels and fragmented IDs.
      - `label` string, required
      - `subjects` object, required
  - `retention` 'ephemeral' | 'session', required: `ephemeral` stores no per-turn input or output, only usage. `session` also stores each turn's input and output so a repeated `turn_key` replays it.
  - `ttl_s` integer: Conversation lifetime in seconds.

## Response `201`

Successful Response

- CreateConversationResponse
  - `conversation_id` string, required
  - `expires_at` string, date-time, required
  - `cache_expires_at` string, date-time, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-06** `bc15cec7e794`: 2 info
  - added the new optional request property `media_binding/anyOf[subschema #2: MediaBindingIn]/people`
  - added the new optional request property `media_bindings/anyOf[subschema #1]/items/people`
- **2026-10-07** `45bdd041d683`: 1 info
  - added the new optional request property `media_bindings`
- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/insights/conversations/post.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)