---
title: "Create Collection"
method: POST
path: "/collections"
tags: ["collections"]
---

# Create Collection

`POST /collections`

Create a new collection in your organization.

Collections are containers for organizing and searching across data from multiple
sources. After creation, add source connections to begin syncing data.

The collection will be assigned a unique `readable_id` based on the name you provide,
which is used in URLs and API calls. You can optionally configure:

- **Sync schedule**: How frequently to automatically sync data from all sources
- **Custom readable_id**: Provide your own identifier (must be unique and URL-safe)

## Request body

- CollectionCreate — Schema for creating a new collection. Collections serve as logical containers for organizing related data sources. Once created, you can add source connections to populate the collection with data from various sources like databases, APIs, and file systems. You can optionally set a default sync configuration that will apply to all syncs within this collection unless overridden at the sync or job level.
  - `name` string, required — Human-readable display name for the collection. This appears in the UI and should clearly describe the data contained within (e.g., 'Finance Data').
  - `readable_id` string, nullable — URL-safe unique identifier used in API endpoints. Must contain only lowercase letters, numbers, and hyphens. If not provided, it will be automatically generated from the collection name with a random suffix for uniqueness (e.g., 'finance-data-ab123').
  - `sync_config` SyncConfig — Sync configuration with automatic env var loading. Env vars use double underscore as delimiter: SYNC_CONFIG__HANDLERS__ENABLE_VECTOR_HANDLERS=false
    - `destinations` DestinationConfig — Controls where entities are written.
      - `skip_vespa` boolean — Skip writing to native Vespa
      - `target_destinations` string[], nullable — If set, ONLY write to these destination UUIDs
      - `exclude_destinations` string[], nullable — Skip these destination UUIDs
    - `handlers` HandlerConfig — Controls which handlers run during sync.
      - `enable_vector_handlers` boolean — Enable VectorDBHandler
      - `enable_raw_data_handler` boolean — Enable RawDataHandler (ARF)
      - `enable_postgres_handler` boolean — Enable EntityPostgresHandler
    - `cursor` CursorConfig — Controls incremental sync cursor behavior.
      - `skip_load` boolean — Don't load cursor (fetch all entities)
      - `skip_updates` boolean — Don't persist cursor progress
    - `behavior` BehaviorConfig — Miscellaneous execution behavior flags.
      - `skip_hash_comparison` boolean — Force INSERT for all entities
      - `replay_from_arf` boolean — Replay from ARF storage instead of calling source
      - `skip_guardrails` boolean — Skip usage guardrails (entity count checks)

## Response `200`

Created collection

- Collection — API-facing collection schema with embedding metadata. Extends CollectionRecord with vector_size and embedding_model_name, which are resolved by the CollectionService from the deployment metadata and the dense embedder registry. Excludes vector_db_deployment_metadata_id (internal FK).
  - `name` string, required — Human-readable display name for the collection.
  - `readable_id` string, required — URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created.
  - `id` string, uuid, required — Unique system identifier for the collection. This UUID is generated automatically and used for internal references.
  - `sync_config` SyncConfig — Sync configuration with automatic env var loading. Env vars use double underscore as delimiter: SYNC_CONFIG__HANDLERS__ENABLE_VECTOR_HANDLERS=false
    - `destinations` DestinationConfig — Controls where entities are written.
      - `skip_vespa` boolean — Skip writing to native Vespa
      - `target_destinations` string[], nullable — If set, ONLY write to these destination UUIDs
      - `exclude_destinations` string[], nullable — Skip these destination UUIDs
    - `handlers` HandlerConfig — Controls which handlers run during sync.
      - `enable_vector_handlers` boolean — Enable VectorDBHandler
      - `enable_raw_data_handler` boolean — Enable RawDataHandler (ARF)
      - `enable_postgres_handler` boolean — Enable EntityPostgresHandler
    - `cursor` CursorConfig — Controls incremental sync cursor behavior.
      - `skip_load` boolean — Don't load cursor (fetch all entities)
      - `skip_updates` boolean — Don't persist cursor progress
    - `behavior` BehaviorConfig — Miscellaneous execution behavior flags.
      - `skip_hash_comparison` boolean — Force INSERT for all entities
      - `replay_from_arf` boolean — Replay from ARF storage instead of calling source
      - `skip_guardrails` boolean — Skip usage guardrails (entity count checks)
  - `created_at` string, date-time, required — Timestamp when the collection was created (ISO 8601 format).
  - `modified_at` string, date-time, required — Timestamp when the collection was last modified (ISO 8601 format).
  - `organization_id` string, uuid, required — Identifier of the organization that owns this collection. Collections are isolated per organization.
  - `created_by_email` string, email, nullable — Email address of the user who created this collection.
  - `modified_by_email` string, email, nullable — Email address of the user who last modified this collection.
  - `status` 'ACTIVE' | 'NEEDS SOURCE' | 'ERROR' — Collection status enum.
  - `vector_size` integer, required — Vector dimensions used by this collection (derived from deployment metadata).
  - `embedding_model_name` string, required — Name of the embedding model used for this collection (derived from deployment metadata).
  - `source_connection_summaries` SourceConnectionSummary[] — Lightweight list of source connections attached to this collection. Contains only short_name and name, suitable for rendering icons in list views.
    - `short_name` string, required
    - `name` string, required

## Other responses

- `422` — Validation Error
- `429` — Rate Limit Exceeded

---

[API](https://skmtc.net/airweave-ai/apis/airweave.md) · [All operations](https://skmtc.net/airweave-ai/apis/airweave/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airweave-ai/airweave/revisions/bf410c28c0c6/schema)