---
title: "Start a cross-examination session"
method: POST
path: "/cross-examinations"
tags: ["Cross-examination"]
---

# Start a cross-examination session

`POST /cross-examinations`

## Request

- Base URL: `https://api.suprememind.ai/v1`
- URL: `https://api.suprememind.ai/v1/cross-examinations`
- Auth: HTTP bearer

Requires the `cross_exam` scope. A witness modelled on an expert class, on one
matter: `oppose` (the default) examines the other side's expert, `prepare`
rehearses your own. Charged exactly as in the app: 0.2 credits, at the start,
once; free on an example matter. A session holds 25 questions; the answers
inside it are free. The transcript is kept on the matter, where the app's
Practice tab shows it. With a test key the witness gives fixed sample answers
and nothing is charged. Idempotency-Key makes a retried start safe.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `matter_id` string, required
  - `expert_class` string, required: An id from GET /expert-classes.
  - `mode` 'oppose' | 'prepare'
  - `difficulty` 'cooperative' | 'hostile'

## Response `201`

The session.

- CrossExamination
  - `id` string, required
  - `object` 'cross_examination', required
  - `livemode` boolean, required
  - `status` 'active' | 'ended', required
  - `matter_id` string, required
  - `expert_class` string, nullable
  - `mode` 'oppose' | 'prepare', required
  - `difficulty` 'cooperative' | 'hostile'
  - `questions_asked` integer, required
  - `question_limit` 25, required
  - `charged_credits` number, required
  - `created_at` string, date-time, required
  - `ended_at` string, date-time, nullable
  - `transcript` object[]
    - `role` 'counsel' | 'witness'
    - `text` string
  - `debrief` string
  - `superseded` boolean
  - `sample` object
    - `note` string

## Other responses

- `400`: The request was malformed.
- `401`: Missing, malformed, unknown or revoked key.
- `402`: The firm does not have enough credits. `balance` and `required` say by how much. `reason: "fair_use_cap"` means the matter is on a matter plan and has passed the plan's weekly fair-use limit, so the work is paid in credits; credits can be bought in the app at any time.
- `403`: The key lacks the scope, the address is not on its allowlist, or API access is off for the account.
- `404`: Nothing with that id is visible to this key.
- `422`: This Idempotency-Key was already used with a different request.
- `429`: Too many requests, or too many jobs in flight.

---

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