---
title: "POST /api/v1/sync"
method: POST
path: "/api/v1/sync"
tags: ["v1"]
---

# POST /api/v1/sync

`POST /api/v1/sync`

## Request

- Base URL: `https://api.overmindlab.ai`
- URL: `https://api.overmindlab.ai/api/v1/sync`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Api-Key`
  - HTTP bearer

Two-way ``overmind.toml`` sync.

POST pushes the local snapshot. The server reconciles capability identity —
carry / leftover / remount — and never deletes: absence sets
``status=leftover`` (observed rows stay). ``archived=true`` keeps leftover.
POST response is the incoming set with ids filled in. GET returns leftovers
with ``archived=true`` so toml round-trips them without listing them in the
console.

Auth: ``X-Api-Key`` (``APIToken``). Project keys must match ``project_id``;
account keys may sync any project the user belongs to.

## Request body

- SyncSnapshotRequest: Wire form of ``overmind.toml`` — the unit of two-way sync.
  - `project_id` string, uuid, required
  - `repo_summary` string
  - `trace_provider` 'overmind' | 'langfuse' | 'langsmith' | 'opentelemetry': * `overmind` - overmind * `langfuse` - langfuse * `langsmith` - langsmith * `opentelemetry` - opentelemetry
  - `version` string, required
  - `repository_snapshot` RepositorySnapshotRequest
    - `repository` string, required
    - `directory` string, required
    - `branch` string, required
    - `commit` string, required
    - `dirty` boolean, required
    - `fingerprint` string, required
    - `scanned_at` string, date-time, required
  - `capabilities` CapabilityRequest[], required
    - `tool_config` unknown
    - `consistency_rules` unknown
    - `optimizable_elements` unknown
    - `fixed_elements` unknown
    - `name` string, required
    - `description` string
    - `source_path` string
    - `entrypoint_fn` string
    - `model` string
    - `analyzer_model` string
    - `cli_version` string
    - `status` 'current' | 'leftover' | 'deleted': * `current` - Current * `leftover` - Leftover * `deleted` - Deleted
    - `observed` boolean
    - `footprint` unknown
    - `input_schema` unknown
    - `output_fields` unknown
    - `output_schema` unknown
    - `structure_weight` number, double
    - `total_points` number, double
    - `tool_usage_weight` number, double
    - `policy_markdown` string
    - `tools_summary` string
    - `decision_logic` string
    - `improvement_metadata` unknown
    - `usage_stats` unknown
    - `last_activity_at` string, date-time, nullable
    - `project` string, uuid, required
    - `active_eval_set` string, uuid, nullable
    - `active_model` string, uuid, nullable
    - `benchmark_model` string, uuid, nullable

## Response `200`

- SyncSnapshot: Wire form of ``overmind.toml`` — the unit of two-way sync.
  - `project_id` string, uuid, required
  - `repo_summary` string
  - `trace_provider` 'overmind' | 'langfuse' | 'langsmith' | 'opentelemetry': * `overmind` - overmind * `langfuse` - langfuse * `langsmith` - langsmith * `opentelemetry` - opentelemetry
  - `version` string, required
  - `repository_snapshot` RepositorySnapshot
    - `repository` string, required
    - `directory` string, required
    - `branch` string, required
    - `commit` string, required
    - `dirty` boolean, required
    - `fingerprint` string, required
    - `scanned_at` string, date-time, required
  - `last_synced_at` string, date-time, nullable, required
  - `capabilities` Capability[], required
    - `id` string, uuid, required
    - `activation` ModelActivation, required
      - `id` string, uuid, required
      - `target` string, uuid, nullable, required
      - `stage` 'checking' | 'verifying' | 'switching' | 'complete' | 'failed' | 'cancelled', required: * `checking` - Checking deployment * `verifying` - Waking and verifying inference * `switching` - Switching routing * `complete` - Live * `failed` - Failed * `cancelled` - Cancelled
      - `failed_stage` string, required
      - `error` string, required
      - `started_at` string, date-time, required
      - `completed_at` string, date-time, nullable, required
    - `tool_config` unknown
    - `consistency_rules` unknown
    - `optimizable_elements` unknown
    - `fixed_elements` unknown
    - `dataset_size` integer, required
    - `flow` CapabilityFlow, required: Typed execution-graph contract for one capability (see ``build_capability_flow``).
      - `has_card` boolean, required
      - `is_fallback` boolean, required
      - `source` string, required
      - `model_resolution` CapabilityFlowModelResolution
        - `default_model` string, required
        - `selection` string, required
        - `provenance` string[], required
      - `task` string, required
      - `modality` string, required
      - `domain` string, required
      - `model` string, required
      - `system_prompt` string, required
      - `system_prompt_excerpt` string, required
      - `takes_files` boolean, required
      - `input_schema` object, required
      - `output_fields` object, required
      - `expected_output` CapabilityFlowExpectedOutput, required
        - `description` string, required
        - `example` unknown
        - `quality_signals` string[]
      - `tool_spec` CapabilityFlowTool[], required
        - `name` string, required
        - `purpose` string, required
        - `args` string, required
        - `side_effect` string
        - `returns` string
        - `arguments` CapabilityFlowToolArgument[]
          - `name` string, required
          - `type` string
          - `required` boolean
          - `description` string
        - `branches` CapabilityFlowToolBranch[]
          - `transitions` CapabilityFlowTransition[]
            - `target` string, required
            - `condition` string, required
          - `condition` string, required
          - `basis` string, required
          - `action` string, required
          - `outcome` string, required
          - `next` string, required
          - `provenance` string[], required
        - `integration` string
        - `cluster` string
        - `provenance` string[]
      - `modes` CapabilityFlowMode[], required
        - `name` string, required
        - `entrypoint_fn` string, required
        - `source_path` string, required
        - `prompt_builder` string
        - `purpose` string
        - `routing` string
        - `model` string
        - `output` string
        - `prompt` string
        - `prompt_excerpt` string
      - `llm_utilities` CapabilityFlowUtility[], required
        - `name` string, required
        - `purpose` string, required
        - `called_by` string, required
        - `source_path` string, required
        - `entrypoint_fn` string, required
        - `model` string, required
        - `io_contract` string
        - `cardinality` string
        - `prompt_excerpt` string
        - `structured_output` boolean
      - `vocabulary` object, required
      - `success_criteria` string[], required
      - `failure_modes` string[], required
      - `trajectory_map` CapabilityFlowTrajectoryPath[], required
        - `id` string, required
        - `name` string, required
        - `claim` string
        - `prompt_quote` string
        - `verified` boolean
        - `routing` string, required
        - `steps` CapabilityFlowTrajectoryStep[]
          - `transitions` CapabilityFlowTransition[]
            - `target` string, required
            - `condition` string, required
          - `step` string, required
          - `kind` string
          - `anchors` string[]
          - `input` string
          - `action` string
          - `output` string
          - `may_use` CapabilityFlowTrajectoryToolUse[]
            - `tool` string, required
            - `when` string, required
        - `tools` string[], required
        - `terminal` CapabilityFlowTrajectoryTerminal, required
          - `kind` string, required
          - `description` string, required
        - `divergences` string[], required
        - `provenance` string[], required
      - `provenance_paths` string[], required
    - `name` string, required
    - `slug` string, required
    - `description` string
    - `source_path` string
    - `entrypoint_fn` string
    - `model` string
    - `analyzer_model` string
    - `cli_version` string
    - `status` 'current' | 'leftover' | 'deleted': * `current` - Current * `leftover` - Leftover * `deleted` - Deleted
    - `observed` boolean
    - `footprint` unknown
    - `input_schema` unknown
    - `output_fields` unknown
    - `output_schema` unknown
    - `structure_weight` number, double
    - `total_points` number, double
    - `tool_usage_weight` number, double
    - `policy_markdown` string
    - `tools_summary` string
    - `decision_logic` string
    - `active_model_activated_at` string, date-time, nullable, required
    - `first_application_request_at` string, date-time, nullable, required
    - `last_application_request_at` string, date-time, nullable, required
    - `improvement_metadata` unknown
    - `usage_stats` unknown
    - `last_activity_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `project` string, uuid, required
    - `active_eval_set` string, uuid, nullable
    - `active_model` string, uuid, nullable
    - `previous_active_model` string, uuid, nullable, required
    - `benchmark_model` string, uuid, nullable

---

[API](https://skmtc.dev/overmindlab/apis/overmind-api.md) - [All operations](https://skmtc.dev/overmindlab/apis/overmind-api/llms.txt) - [OpenAPI document](https://skmtc.dev/overmindlab/apis/overmind-api/revisions/0ecfd39e80c6?raw)