---
title: "Run Expert Skill"
method: POST
path: "/v2/insights/expert/{skill}"
---

# Run Expert Skill

`POST /v2/insights/expert/{skill}`

## 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/expert/{skill}`
- Auth: OAuth 2
  - Authorization code: `https://api.imentiv.ai/oauth/authorize`
  - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `insights.write`, `media.read`

Run one emotion expert skill on a window of a processed recording the user may read.

Takes a user's delegated access token with the `insights.write` scope; an API key or a
browser session is refused with 403. The recording must be readable by that user, which
also needs `media.read` (403 naming the scope otherwise): their own, or, on a grant bound to
their team workspace, one that workspace owns. A recording they may not read and a missing
one are the same 404 `binding_not_found`. The call is billed to that user, or to their team
workspace where the deployment is that workspace's own, with your app recorded on the
charge, and the stored result belongs to that user and your app.

Skills: `interpret_window` (what the subject appears to feel, optionally for a
`question`), `assess_response` (whether the subject responded to a `stimulus`, against
a `baseline`), `explain_moment` (why a detected moment, `moment_id`, was flagged; videos
only), `compare` (two to four `people` side by side) and `narrate` (the emotional arc of
the window, optionally for a `focus`). A field that belongs to another skill is 422.

The recording must be fully processed (409 `media_not_ready` otherwise), and one with
several people needs a subject per requested modality (422 `subject_required`).
`situation` sections are treated as data about the situation, never as instructions.

Every finding cites evidence on the recording: evidence windows and moments. Confidence
is capped by how reliable the emotion models are for each state, language and
condition; `evidence_quality` says why. `insufficient_evidence` and `out_of_scope` are
results (200), not errors. `explain_moment` answers 409 `moments_not_ready` while the
recording's moments are computed, and 422 `moments_unavailable` when they will not be.
A call that does not finish in time is 504 `evaluate_timeout`.

A call that produces a new result is billed once, after the response. A repeat of an
identical request from the same app with the same `expert_version` replays the stored
result free of charge (`replayed: true`); while the first is still running a repeat is 409
`expert_in_progress`. Another app's identical request is evaluated, and billed, on its own.
Four results are free: a request outside the skills' scope, a window with no usable evidence,
and an answer that failed citation grounding or the output schema. A stored answer is billed
whatever its status, including `insufficient_evidence` and `out_of_scope` answers and one
whose findings calibration then withholds. Failed calls are not billed. Stored results are kept for 30 days and
deleted with the recording or the account; there is no per-result delete.

## Path parameters

- `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required

## Request body

- ExpertSkillRequest: One skill call on one recording.
  - `product` string, required: The calling application's tag, recorded for usage reporting only.
  - `language` string, nullable: The spoken language, when known. It can only lower a reading's confidence.
  - `condition` string: The recording condition: `default`, `in_cabin_ir`, `off_axis_gt30` or `road_noise`. A condition other than `default` can only lower a reading's confidence.
  - `media_binding` ExpertMediaBindingIn, required: One of the caller's own processed recordings, with at most one subject per modality.
    - `media_id` string, required
    - `media_type` 'video' | 'audio', required
    - `subjects` object, nullable: Per modality, the one subject id to read. Required for a requested modality with more than one subject in the recording; a modality with exactly one is chosen automatically.
  - `window` WindowIn, required: A half-open window `[start_ms, end_ms)` on the bound media's clock.
    - `start_ms` integer, required
    - `end_ms` integer, required
  - `modalities` string[]: The modalities to read, each at most once.
  - `situation` SituationIn[]
    - `type` string, required: Section type chosen by the application.
    - `text` string, required
  - `question` string, nullable: `interpret_window` only: what to interpret the window for.
  - `stimulus` StimulusIn: What the subject may have responded to, on the recording's clock.
    - `onset_ms` integer, required: When the stimulus began. Must be inside `window`.
    - `end_ms` integer, nullable: When it ended, if known.
    - `label` string, nullable: A short name for the stimulus.
  - `baseline` WindowIn: A half-open window `[start_ms, end_ms)` on the bound media's clock.
    - `start_ms` integer, required
    - `end_ms` integer, required
  - `moment_id` string, nullable: `explain_moment` only, and required there: a moment of the chosen face in `window`.
  - `people` object, nullable: `compare` only, and required there: two to four people, each a label mapped to one subject id per requested modality. Replaces the binding's `subjects`.
  - `focus` string, nullable: `narrate` only: what to narrate for.

## Response `200`

Successful Response

- ExpertResponse
  - `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required
  - `expert_version` string, required: Identifies everything that shaped the result; part of its cache key.
  - `result` ExpertResult, required: One skill result. Anything but `ok` carries no findings.
    - `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required
    - `status` 'ok' | 'insufficient_evidence' | 'out_of_scope', required: `insufficient_evidence` when coverage, grounding or calibration cannot support a finding; `out_of_scope` when the question or focus is not about observed emotion.
    - `expert_version` string, required
    - `reason` string, required
    - `evidence_quality` string[]: Stable codes describing the evidence, e.g. `untested_modality:face` or `low_confidence_language:de`.
    - `quality_notes` ExpertClaim[]
      - `text` string, required
      - `citations` ExpertCitation[]
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
    - `confounds` ExpertClaim[]
      - `text` string, required
      - `citations` ExpertCitation[]
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
    - `alternatives` ExpertClaim[]
      - `text` string, required
      - `citations` ExpertCitation[]
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
    - `citations` ExpertCitation[]
      - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
      - `modality` 'face' | 'voice' | 'text', required
      - `subject` string, required: The person the evidence belongs to.
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `readings` ExpertReading[]
      - `state` string, required
      - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
      - `supporting_modalities` string[], required
      - `citations` ExpertCitation[], required
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
      - `note` string, required
    - `verdict` 'response' | 'no_response', nullable
    - `direction` string, nullable
    - `magnitude` 'low' | 'medium' | 'high', nullable
    - `onset_ms` integer, nullable
    - `below_engine_threshold` boolean, nullable
    - `baseline_used` ExpertWindow
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `threshold_reference` string, nullable
    - `drivers` string[]
    - `robustness` ExpertClaim[]
      - `text` string, required
      - `citations` ExpertCitation[]
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
    - `counterevidence` string[]
    - `contrasts` ExpertReading[]
      - `state` string, required
      - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
      - `supporting_modalities` string[], required
      - `citations` ExpertCitation[], required
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
      - `note` string, required
    - `arc` ExpertArcStep[]
      - `window` ExpertWindow, required
        - `start_ms` integer, required
        - `end_ms` integer, required
      - `reading` ExpertReading, required: One observed emotional state, with its confidence after calibration.
        - `state` string, required
        - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
        - `supporting_modalities` string[], required
        - `citations` ExpertCitation[], required
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
        - `note` string, required
  - `credits_charged` integer, required: Credits for this call, charged after the response; 0 on a replay.
  - `replayed` boolean, required: An identical earlier request's stored result, returned free of charge.
  - `model_ids` object, required: Per modality, the emotion model version the readings were calibrated against; null when the recording does not name one, and that modality is then reported as untested.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-07** `45bdd041d683`: 1 info
  - the endpoint scheme security `OAuth2Delegated` was added to the API
- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/insights/expert/:skill/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)