---
title: "Add a document to a vault"
method: POST
path: "/vaults/{id}/documents"
tags: ["Contract Intelligence"]
---

# Add a document to a vault

`POST /vaults/{id}/documents`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/vaults/{id}/documents`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/vaults/:id/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

Upload one document into a Contract Intelligence vault as multipart form data. The document is stored, its text is extracted, and it is then scanned against the vault's columns, so its extracted fields appear in the vault View a few minutes later.

Vaults accept a narrower set of formats than the rest of GC AI: PDF, Word (`.doc`, `.docx`), and plain text (`.txt`). Scanned and image-based PDFs are supported through OCR. Spreadsheets, presentations, standalone images, and email files are rejected.

Requires the `editor` or `owner` role in the vault and the organization-level permission to manage vaults; a caller with the role but not the permission gets `403`. A vault that has reached its document capacity or whose organization has no remaining allowance returns `409` with the same message the app shows, and stores nothing. While a vault is still in guided setup, documents are stored and scanned once setup finishes.

Requires a user-scoped API key (`u:gcai_...`). A vault is shared with named people, so an organization-scoped key has no identity to resolve vault access with.

## Path parameters

- `id` string, uuid, required: The vault ID

## Request body `multipart/form-data`

- VaultDocumentUploadRequest
  - `file` string, binary, required: The document to add to the vault. PDF, Word (.doc/.docx), and plain text (.txt) only.

## Response `200`

Document added to the vault

- VaultDocumentResponse
  - `id` string, uuid, required: Unique file identifier for the uploaded document. Poll `GET /files/{id}` until `status` is `ready`.
  - `vault_id` string, uuid, required: The vault the document was added to
  - `name` string, required: Original filename
  - `size` number, required: File size in bytes
  - `content_type` string, required: MIME type of the document
  - `status` 'extracting' | 'embedding' | 'ready' | 'failed', required: Text-extraction status of the document
  - `created_at` string, required: ISO 8601 creation timestamp

## Other responses

- `400`: Invalid request (missing file, unsupported file type for a vault, or file too large)
- `401`: Missing or malformed API key
- `403`: Contract Intelligence is not enabled for this account. Contact support to request access., or the caller's vault role cannot add documents
- `404`: Vault not found or access denied
- `409`: The vault is archived, or the vault or organization cannot accept more documents right now (capacity or allowance reached); nothing was stored
- `422`: Vault access is per-user and requires a user-scoped API key (u:gcai_...).
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)