> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Connector Sync > Create a connector sync configuration. ## OpenAPI ````yaml POST /orgs/{org_id}/connectors/{connector_id}/syncs openapi: 3.1.0 info: title: Timbal Platform API description: Public API documentation for the Timbal platform license: name: '' version: 2.0.0 servers: - url: https://api.timbal.ai description: Production - url: https://api.dev.timbal.ai description: Development security: [] tags: - name: ace description: Action Control Engine (ACE) operations - name: alarms description: Metric series and threshold alarms - name: analytics description: Org and project analytics - name: billing description: Subscriptions, usage, and payment-related operations - name: channels description: Delivery channels alarms notify through - name: content description: Re-sign stored content URLs - name: files description: File operations - name: iam description: IAM — actions, roles, users, and authorization introspection - name: k2 description: Knowledge Bases v2 operations - name: orgs description: Organization operations - name: projects description: Project operations - name: runs description: Execution operations - name: templates description: Public project template catalog - name: users description: Authenticated user profile paths: /orgs/{org_id}/connectors/{connector_id}/syncs: post: tags: - connectors summary: '`POST /orgs/{org_id}/connectors/{connector_id}/syncs`' description: Create a connector sync configuration. operationId: create parameters: - name: org_id in: path required: true schema: type: string - name: connector_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSyncReq' required: true responses: '201': description: Sync created content: application/json: schema: $ref: '#/components/schemas/CreateSyncRes' '400': description: Invalid request '403': description: Forbidden '404': description: Connector or KB not found '422': description: Source or full-refresh extraction unsupported by connector security: - bearer_auth: [] components: schemas: CreateSyncReq: type: object required: - kb_id - dest_table - source - interval_secs properties: dest_table: type: string description: |- Destination table inside the KB. Created by the first run when it doesn't exist yet; when it does, `existing_dest` decides whether the sync continues it or rebuilds it. existing_dest: oneOf: - type: 'null' - $ref: '#/components/schemas/ExistingDest' description: >- How to treat a `dest_table` that already exists. Defaults to `adopt`. Only meaningful for an incremental sync — a full-refresh one replaces the destination on every run by definition. initial_cursor: type: - object - 'null' description: >- Checkpoint to continue an existing `dest_table` from, overriding the one read off the table itself. Only valid when the table exists and `existing_dest` is `adopt` — for a table the sync still has to build, use `start_cursor`. Same shape as `start_cursor`. interval_secs: type: integer format: int64 description: >- Seconds between run *starts*. The scheduler ticks every 30s, so smaller values effectively mean "every tick". kb_id: type: integer format: int64 description: Target KB (numeric id, same as the `/k2` routes). key_columns: type: - array - 'null' items: type: string description: >- Ordered destination `PRIMARY KEY` columns. Omit for a keyless table. The first run declares the key; later runs then **merge** on it (upsert) so an upstream update — or a re-pulled boundary row from a non-unique cursor — overwrites in place instead of duplicating. Key columns are auto-added to a `columns` subset, so they only need to exist on the source table. Source these from the browse columns' `pk_position`. name: type: - string - 'null' description: Operator label. source: $ref: '#/components/schemas/SourceBody' start_cursor: type: - object - 'null' description: >- Optional lower bound for the **first** run when it builds the table: only rows with `cursor_column >= start_cursor` are pulled (e.g. seed a timestamp to backfill "from last month on" instead of the whole table). Ignored on later runs — the advancing cursor takes over — and ignored when the sync adopts an existing table. Shape matches the job `cursor` (e.g. `{"kind":"timestamp","value":"2026-06-01T00:00:00Z"}`). Not valid on a full-refresh sync (no `cursor_column` to bound). CreateSyncRes: type: object required: - sync_id - adopted_dest_table - key_columns properties: adopted_dest_table: type: boolean description: >- `true` when the sync continues an existing destination table instead of building it on the first run. initial_cursor: type: - object - 'null' description: >- The checkpoint the first run resumes from when the destination was adopted; `null` otherwise (including an adopted table that was empty). key_columns: type: array items: type: string description: >- Primary-key columns the sync will merge on. Inherited from an adopted table's own key when the request didn't declare one. sync_id: type: string ExistingDest: type: string description: >- What to do when `dest_table` already holds data — typically because a one-off job extracted it and the sync is being added afterwards to keep it fresh. enum: - adopt - replace SourceBody: oneOf: - allOf: - $ref: '#/components/schemas/RelationalSourceBody' - type: object required: - kind properties: kind: type: string enum: - postgres - allOf: - $ref: '#/components/schemas/RelationalSourceBody' - type: object required: - kind properties: kind: type: string enum: - sql_server - allOf: - $ref: '#/components/schemas/RelationalSourceBody' - type: object required: - kind properties: kind: type: string enum: - mysql description: >- The source half of a dispatch, tagged by `kind`. Each variant maps to a `SourceSpec` and gates on the connector advertising the matching `source:` capability. Request shape: `"source": { "kind": "sql_server", "connection_ref": "...", "table": "...", "cursor_column": "..." }`. RelationalSourceBody: type: object description: |- Shared shape for the relational sources (Postgres, SQL Server, MySQL). `schema` defaults per-source (`public` / `dbo` / the connection DSN's default database — on MySQL `schema` *is* the database name). required: - connection_ref - table properties: columns: type: - array - 'null' items: type: string description: Projection; omit for all columns. connection_ref: type: string description: |- Name of a connection in the connector's local `connections.json`. The DSN itself never leaves the connector box. cursor_column: type: - string - 'null' description: >- Monotonic column for incremental extraction (`id`, `updated_at`, ...). Omit for a *snapshot* (full-scan) pass over the whole table, unordered and with no checkpoint/resume — for tables with no usable cursor (requires the connector to advertise `extract:snapshot`, 0.1.25+). On a sync that makes every run a full refresh of the destination. schema: type: - string - 'null' description: Source schema; defaults to `public` (Postgres) / `dbo` (SQL Server). table: type: string description: Source table to extract. securitySchemes: bearer_auth: type: http scheme: bearer description: >- Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information. ````