---
title: "Create a vault"
method: POST
path: "/vaults"
tags: ["Contract Intelligence"]
---

# Create a vault

`POST /vaults`

## Request

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

Create a Contract Intelligence vault. The caller becomes its `owner`, and the vault starts access-controlled, so nobody else can see it until you add members or turn access control off.

A vault created here skips guided setup and is ready for documents right away: upload with `POST /vaults/{id}/documents`, add columns with `POST /vaults/{id}/columns`, and read the extracted table from `GET /vaults/{id}/documents`. In the app a vault waits in guided setup, and documents added meanwhile are stored but not scanned. There is no guided setup over the API, so this endpoint finishes setup as it creates the vault and every upload is scanned as it arrives.

Creating a vault needs the organization-level permission to create vaults, which an organization admin grants. Vault names do not have to be unique.

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.

## Request body

- VaultCreateRequest
  - `name` string: Vault name. Omit it and GC AI allocates the next free default name (`New Vault`, `New Vault (2)`, and so on).
  - `description` string: Optional description shown beside the vault name

## Response `201`

The created vault

- VaultResponse
  - `id` string, uuid, required: Unique vault identifier
  - `name` string, required: Vault name
  - `description` string, nullable, required: Vault description, or null if unset
  - `my_role` 'owner' | 'editor' | 'viewer', required: Caller's role in this vault: `owner` (manage members and settings), `editor` (add documents and edit extracted data), or `viewer` (read and annotate). A vault the caller reaches only through organization-wide visibility reports `viewer`. The role is not the whole story for writes: adding documents also needs the organization-level permission to manage vaults, so a caller can hold `editor` here and still receive `403` from `POST /vaults/{id}/documents`.
  - `is_access_controlled` boolean, required: When true, only vault members can see the vault. When false, any member of the organization with organization-wide vault read can see it.
  - `document_count` number, required: Documents that have finished scanning in this vault. Documents still being read are not counted yet.
  - `setup_completed_at` string, nullable, required: ISO 8601 timestamp when guided setup finished, or null while the vault is still in setup. Documents added to a vault in setup are stored but not scanned until setup finishes. Vaults created through `POST /vaults` finish setup immediately, so this is always set for them.
  - `archived_at` string, nullable, required: ISO 8601 timestamp when the vault was archived, or null while it is live. Archived vaults are hidden from the default list and reject changes until `POST /vaults/{id}/restore` runs.
  - `created_at` string, required: ISO 8601 creation timestamp
  - `updated_at` string, required: ISO 8601 last-update timestamp

## Other responses

- `400`: Invalid request body
- `401`: Missing or malformed API key
- `403`: Contract Intelligence is not enabled for this account. Contact support to request access., or the caller cannot create vaults
- `409`: A vault with that name already exists
- `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)