---
title: "Update Collection"
method: PATCH
path: "/collections/{readable_id}"
tags: ["collections"]
---

# Update Collection

`PATCH /collections/{readable_id}`

## Request

- Base URL: `https://api.airweave.ai`
- URL: `https://api.airweave.ai/collections/{readable_id}`
- Auth: API key in header `x-api-key`

Update an existing collection's properties.

You can modify:
- **Name**: The display name shown in the UI
- **Sync configuration**: Schedule settings for automatic data synchronization

Note that the `readable_id` cannot be changed after creation to maintain stable
API endpoints and preserve existing integrations.

## Path parameters

- `readable_id` string, required: The unique readable identifier of the collection to update

## Request body

- CollectionUpdate: Schema for updating an existing collection. Allows updating the collection's display name and default sync configuration. The readable_id is immutable to maintain stable API endpoints and references.
  - `name` string, nullable: Updated display name for the collection. Must be between 4 and 64 characters.
  - `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`

Updated 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

- `404`: Collection Not Found
- `422`: Validation Error
- `429`: Rate Limit Exceeded

## Changes

> 63 revisions in range; 2 not diffed.

- **2026-03-22** `a8105b372b4d`: 1 info
  - added the optional property `source_connection_summaries` to the response with the `200` status
- **2026-02-09** `573e671e8777`: 2 warning
  - removed the request property `sync_config/anyOf[subschema #1: SyncConfig]/destinations/skip_qdrant`
  - removed the optional property `sync_config/anyOf[subschema #1: SyncConfig]/destinations/skip_qdrant` from the response with the `200` status
- **2026-02-04** `9c8b36d8fcaa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/airweave-ai/apis/airweave/changes/collections/:readable_id/patch.md)

---

[API](https://skmtc.dev/airweave-ai/apis/airweave.md) - [All operations](https://skmtc.dev/airweave-ai/apis/airweave/llms.txt) - [OpenAPI document](https://skmtc.dev/airweave-ai/apis/airweave/revisions/bf410c28c0c6?raw)