---
title: "Create an upload grant"
method: POST
path: "/v1/documents/upload-grants"
tags: ["Documents"]
---

# Create an upload grant

`POST /v1/documents/upload-grants`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/documents/upload-grants`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/documents/upload-grants/post.ts> (a function with typed inputs; its response is checked against the schema)

A short-lived token for uploading one file straight to the document service, into the workspace `workspace_id` names, or, without one, for your document jobs. Free, and works at any balance.

1. `POST` the file to `upload_url` as multipart form data, with the header `X-Upload-Token: <token>` and two parts:
   - `file`: the file.
   - `metadata` (required): JSON such as `{"path": "..."}`. Add `total_size_bytes` for files of 32 MiB or more.
2. The upload's response carries the file under `result.file`.
3. Pass its `workspace_id` and `file_id` as the job's source: `{"type":"workspace_file","workspace_id":...,"file_id":...}`.

The bytes never pass through Drex, so there is no 4.5 MB limit.

## Request body

- object
  - `workspace_id` string: Optional. A workspace from the Workspaces API that this key may use; the file goes into that workspace. Leave it out to upload a file for your document jobs (parse, extract, classify, split, ground).
  - `path` string: Pin the upload to exactly this path in the workspace.
  - `max_bytes` integer: Refuse uploads larger than this.
  - `total_size_bytes` integer: The exact size the upload must have.
  - `ttl_seconds` integer: How long the token works.

## Response `201`

The grant.

- object
  - `workspace_id` string, uuid, required: The workspace the file goes into.
  - `upload_url` string, uri, required: Where to `POST` the file. A document-service URL, not Drex's.
  - `token` string, required: Send as `X-Upload-Token`. Meant for one upload.
  - `expires_at` string, date-time, required
  - `max_bytes` integer, nullable, required: The cap you set, or null for the document service's cap for the file type.

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `404`: `workspace_id` is not a workspace this key may use (`not_found_error`, code `workspace_not_found`).
- `422`: The body is not a JSON object or has an unknown field, or the document service refused it (`invalid_request_error`).
- `429`: Over the account's requests per minute for document routes, or the document service is throttling this account (`rate_limit_error`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable (`service_unavailable`).
- `504`: The document service timed out (`upstream_error`).
- `529`: The public API is paused (code `service_disabled`) (`overloaded`).

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)