---
title: "Sync Collection Schema"
method: POST
path: "/v1/collections/{collection_id}/sync-schema"
tags: ["Collection Schema"]
---

# Sync Collection Schema

`POST /v1/collections/{collection_id}/sync-schema`

Sample documents from Qdrant and automatically discover new fields to add to the collection's output_schema.

    This endpoint:
    - Samples N documents from the collection (default: 1000)
    - Discovers all fields present in actual documents
    - Merges discovered fields into the collection's output_schema (additive only)
    - Optionally cascades schema updates to downstream collections
    - Respects debounce window (max once per 5 minutes, unless force=true)

    The sync operation is additive only - it never removes or changes existing field types.

    Use this endpoint to:
    - Manually trigger schema discovery after data ingestion
    - Force an immediate schema sync (bypassing debounce)
    - Update schemas with new fields discovered in documents

## Path parameters

- `collection_id` string, required — Collection ID to sync schema for

## Request body

- SchemaSyncRequest — Request to sync a collection's schema by sampling documents. Used by: - Manual API calls from users - Automatic triggers from BatchJobPoller
  - `sample_size` integer — Number of documents to sample for schema discovery
  - `force` boolean — Force schema sync even if within debounce window. Default: false (respects 5-minute debounce)
  - `cascade_to_downstream` boolean — Automatically update downstream collections that use this collection as source. Default: true

## Response `200`

Successful Response

- union
  - SchemaSyncResponse — Response from schema sync operation.
    - `success` boolean, required — Whether schema sync succeeded
    - `collection_id` string, required — Collection that was synced
    - `schema_version` integer, required — New schema version
    - `previous_version` integer, required — Previous schema version
    - `fields_added` string[] — List of new fields discovered
    - `fields_total` integer, required — Total fields in output_schema
    - `documents_sampled` integer, required — Number of documents sampled
    - `downstream_collections_updated` string[] — Downstream collections that were updated
    - `message` string, nullable — Additional message or error
  - SchemaSyncSkippedResponse — Response when schema sync was skipped (debounce or disabled).
    - `success` boolean — Request succeeded
    - `skipped` boolean — Schema sync was skipped
    - `reason` string, required — Why sync was skipped
    - `collection_id` string, required — Collection ID
    - `schema_version` integer, required — Current schema version
    - `last_sync` string, nullable — Last sync timestamp

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)