---
title: "Queue a brief"
method: POST
path: "/briefs"
tags: ["Briefs"]
---

# Queue a brief

`POST /briefs`

## Request

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

Requires the `briefs` scope. Queues a brief on a matter against a live expert
class and answers 202 at once; poll `GET /briefs/{id}` or listen for the
`brief.completed` webhook. Credits are charged when the brief is delivered,
never for a brief that fails. The balance is checked before queueing.

`side`, when given, must agree with the side the expert class models. With a
test key the brief is finished on arrival with a sample result and nothing is
charged.

A report analyzed on the matter (`POST /reports/analyze`, or in the app) is
read by every brief on it. `use_matter_target_report: true` makes that
explicit, pins the report as it stands now onto this brief, and refuses the
brief (`no_target_report`) when the matter has none. Send it or
`target_report`, not both.

`holdout` is for evaluation. It names up to 20 cases (typically the ruling a
benchmark will score this brief against, and its appeals) that the brief must
not read: they are withheld from every source the brief draws on, and the
result reports what was withheld under `result.holdout`. It binds this brief
only and does not change the matter.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `matter_id` string, required
  - `expert_class` string, required: An id from GET /expert-classes.
  - `side` 'plaintiff' | 'defense' | 'either'
  - `profile` 'standard' | 'high': Defaults to the firm's setting. `high` costs two credits where it runs a distinct model.
  - `target_report` object: A structured summary of an opposing (or your own) expert report to aim the cross-examination and methodology sections at.
  - `use_matter_target_report` boolean: Aim the brief at the report already analyzed on the matter.
  - `holdout` object[]: For evaluation use. Cases the brief must not read, withheld from every source it draws on. Unknown fields are refused (`bad_holdout`).
    - `case_name` string, required
    - `docket_number` string
    - `opinion_url` string, uri: An http(s) url of the opinion

## Response `202`

The brief was queued (or, for a test key, finished).

- BriefAccepted
  - `id` string, required
  - `object` 'brief', required
  - `livemode` boolean
  - `status` 'queued' | 'succeeded', required
  - `matter_id` string
  - `expert_class` string
  - `created_at` string, date-time, required

## 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.
- `409`: A limit was reached, or a request with the same Idempotency-Key is still running.
- `413`: The body is too large to store.
- `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)