---
title: "Get an upload target, or register an uploaded document"
method: POST
path: "/matters/{id}/documents"
tags: ["Documents"]
---

# Get an upload target, or register an uploaded document

`POST /matters/{id}/documents`

## Request

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

Requires the `documents` scope. Two calls, as in the app:

1. Send `{filename, content_type, size_bytes, designation?}`. The answer (201,
   `document_upload`) holds a short-lived upload target: send the file's bytes
   with `upload.method` to `upload.url` with exactly `upload.headers` (or, with
   the `@vercel/blob` client, `put(pathname, file, {access: "private", token:
   client_token})`). The target is good for 15 minutes, for one file at one
   path, of the declared type, up to 20 MB. The bytes go straight to the
   document store and never through this API.
2. Send `{upload_id}`. The server checks what the store holds at that path
   (size and type, never the caller's word) and registers the document
   (201, `document`). Registering the same upload again answers 200 with the
   same document.

`content_type` must be one the app accepts: PDF, Word (.docx), plain text,
Markdown, PNG, JPEG, GIF, WebP, zip, or a dataset (CSV, TSV, Excel).
`designation` is `public`, `confidential` (the default) or `aeo`.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `filename` string, required
    - `content_type` string, required
    - `size_bytes` integer, required
    - `designation` 'public' | 'confidential' | 'aeo'
  - object
    - `upload_id` string, required

## Response `200`

This upload was already registered; the same document.

- Document
  - `id` integer, required
  - `object` 'document', required
  - `matter_id` string, required
  - `filename` string, required
  - `content_type` string, nullable
  - `size_bytes` integer, nullable
  - `designation` 'public' | 'confidential' | 'aeo', required
  - `include_in_analysis` boolean
  - `created_at` string, date-time, required

## Other responses

- `201`: An upload target (step 1) or the registered document (step 2).
- `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.
- `409`: Nothing has been uploaded for this upload yet (`not_uploaded`), the matter's document limit was reached, or the file is registered to another matter.
- `410`: The upload target expired before the file was registered.
- `413`: The body is too large to store.
- `429`: Too many requests, or too many jobs in flight.
- `503`: Document storage is not configured.

---

[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)