---
title: "Read the matter's documents into its facts"
method: POST
path: "/matters/{id}/extract"
tags: ["Documents"]
---

# Read the matter's documents into its facts

`POST /matters/{id}/extract`

## Request

- Base URL: `https://api.suprememind.ai/v1`
- URL: `https://api.suprememind.ai/v1/matters/{id}/extract`
- Auth: HTTP bearer

Requires the `documents` scope. Queues an extraction job and answers 202 at
once; poll `GET /jobs/{id}` or listen for `extract.completed`. Each document
is read in full, several are merged, and the result is written to the
matter's `case_context` (where the app keeps confirmed facts) with a
per-document `record_index`. Without `document_ids`, every document the key
can see that is included in analysis is read. Free. Document text is never
stored, only the structured facts. Pages that are pictures of text are not
read through the API, so a scanned document fails as unreadable. With a test
key the job finishes at once with a fixed sample and no model is called.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `document_ids` integer[]
  - `domain_hint` 'securities' | 'antitrust'

## Response `202`

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

- JobAccepted
  - `id` string, required
  - `object` 'job', required
  - `kind` 'extract' | 'report', required
  - `livemode` boolean
  - `status` 'queued' | 'succeeded', required
  - `matter_id` string
  - `created_at` string, date-time, required

## Other responses

- `400`: The request was malformed.
- `401`: Missing, malformed, unknown or revoked key.
- `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)