---
title: "Create a private collection of base references."
method: POST
path: "/api/collections"
---

# Create a private collection of base references.

`POST /api/collections`

## Request

- Base URL: `https://okfindex.com`
- URL: `https://okfindex.com/api/collections`
- Auth: none declared. Required headers: `Idempotency-Key`

Collections store references, not copied content. They start private. Owner search reads current files in owned bases and published files in other bases. Publication includes only references to currently public bases; private bases and later additions stay out. Every public read checks base publication again. Private or withdrawn collections return 404. Responses use private, no-store.
Returns: { collection{id,name,visibility,created_at,api,public_url} }

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `name` string, required: Collection name, 1–120 characters.

## Response `201`

{ collection{id,name,visibility,created_at,api,public_url} }

- object
  - `collection` KnowledgeCollection, required
    - `id` string, required: The 64-character ID returned by this API.
    - `name` string, required: The owner-selected collection name.
    - `visibility` string, required: private or public; new collections start private.
    - `created_at` string, required: UTC creation timestamp.
    - `api` string, required: Authorized API URL for this view.
    - `public_url` string, nullable, required: Public collection page, or null before publication.

## Other responses

- `400`: Invalid name, cursor, query or idempotency key.
- `401`: A personal account or API key is required.
- `403`: Organization credentials cannot access personal collections.
- `404`: The collection or base is inaccessible.
- `409`: Collection or reference limit reached.
- `413`: Request body exceeds 2 KiB.
- `415`: Use application/json.
- `503`: Collection storage is unavailable.

---

[API](https://skmtc.dev/okfindex/apis/okf-index.md) · [All operations](https://skmtc.dev/okfindex/apis/okf-index/llms.txt) · [OpenAPI document](https://skmtc.dev/okfindex/apis/okf-index/revisions/4b13ca3c739f?raw)