---
title: "Edit a sync"
method: PUT
path: "/v1/workspaces/{workspace_id}/bases/{base_id}"
tags: ["Syncs"]
---

# Edit a sync

`PUT /v1/workspaces/{workspace_id}/bases/{base_id}`

## Request

- Base URL: `https://api.stacksync.com`
- URL: `https://api.stacksync.com/v1/workspaces/{workspace_id}/bases/{base_id}`
- Auth: HTTP bearer

Replace the mapping of a sync with the whole sync you send: read it, change tables, columns, directions, rate limits or delete protection, and send it back. A table left out of both apps is removed, a new pair is added. The sync is paused while the edit applies and restarted after it. Send `validate_only: true` to run every check without changing the sync.

## Path parameters

- `workspace_id` integer, required
- `base_id` string, uuid, required

## Request body

- EditSyncBody: The whole sync after the edit: read the sync, change it, send it back (the sync is paused and restarted by the edit)
  - `base_id` string, uuid, required: The sync; must equal the `base_id` of the path
  - `base_name` string, required: The name of the sync
  - `base_region` 'besg' | 'usnv', required: The data region of the sync
  - `apps` SyncAppEditInput[], required: Exactly two apps, with their `app_id`
    - `app_id` string, required: The app's id in the sync (read it from the sync); an id the sync does not hold is refused
    - `connection_id` string, uuid, required: The connection of the app; the user of the API key must have created it or it must be shared with the workspace
    - `tables` SyncTableEditInput[], required: The tables to sync after the edit: a table left out of both apps is removed, a new pair is added, a changed `sync_direction` or column list is applied
      - `table_name` string, required: The name of the table in the app (its id is accepted too, BigQuery: `project.dataset.table`). For a table being created: the name of the new table, letters, numbers and underscores, at most 63 characters for database apps
      - `table_mapping_id` string, uuid, required: A UUID you choose, the same for the two tables of a pair and different from every other mapping id
      - `sync_direction` 'bidirectional' | 'incoming' | 'outgoing', required: `bidirectional` (paired with `bidirectional`), `incoming` (only written into, paired with `outgoing`) or `outgoing` (only read from, paired with `incoming`)
      - `table_options` SyncTableOptionsInput: The options of a table in the sync
        - `create_new_table` boolean, required: True to have Stacksync create this table in the app from the other app's table; the table must then not exist yet and the app must support it (`can_create_tables` of the app schema). At most one table of a pair is created
        - `primary_key` SyncPrimaryKeyInput: The primary key column of a table being created, instead of the default `stacksync_record_id_` of type uuid (Postgres apps only)
          - `column_name` string, required: The name of the primary key column: letters, numbers and underscores, at most 63 characters, not a synced column's name
          - `data_type` 'uuid' | 'text' | 'varchar': The type of the column
      - `columns` SyncColumnInput[]: The columns to sync. Left out on both tables of a pair: every column of the table is synced (and created, for a new table). When sent on both tables they must hold the same `column_mapping_id`s
        - `column_name` string, required: The name of the column in the app (its read id is accepted too). For a table being created it is the name of the new column
        - `column_mapping_id` string, uuid, required: A UUID you choose, the same for the two columns of a pair and different from every other mapping id
    - `rate_limit` SyncRateLimit: The most requests Stacksync makes to the app in a period
      - `rate` integer, required: The number of requests allowed per period, 1 to 2147483647
      - `frequency` 1 | 60 | 3600 | 86400, required: The period of the rate in seconds: 1 (per second), 60 (per minute), 3600 (per hour) or 86400 (per day)
    - `app_options` SyncAppOptionsInput: The options of an app in the sync
      - `delete_protection` boolean: True to keep deletes from reaching this app (set on every table of the app)
  - `base_resource_id` string: The stable id of the sync
  - `base_status` string: Accepted and stored as given; leave it out
  - `validate_only` boolean: Run every check of the edit, including reading the apps, and answer the sync as it would be stored without changing it

## Response `200`

The sync after the edit (with `validate_only`, as it would be stored)

- SyncSchemaResponse: The written sync
  - `data` SyncSchema, required: A sync as a create or an edit answers it (the mapping, not the settings: read the sync for those)
    - `base_id` string, uuid: The sync; absent from a `validate_only` create, which creates none
    - `base_name` string, required: The name of the sync
    - `base_region` 'besg' | 'usnv', required: The data region of the sync
    - `base_resource_id` string: The stable id of the sync
    - `base_status` string: The state of the sync when it was sent
    - `apps` SyncSchemaApp[], required: The two apps
      - `app_id` string, required: The id of the app inside the sync
      - `connection_id` string, uuid, required: The connection of the app
      - `rate_limit` SyncRateLimit: The most requests Stacksync makes to the app in a period
        - `rate` integer, required: The number of requests allowed per period, 1 to 2147483647
        - `frequency` 1 | 60 | 3600 | 86400, required: The period of the rate in seconds: 1 (per second), 60 (per minute), 3600 (per hour) or 86400 (per day)
      - `tables` SyncSchemaTable[], required: The synced tables
        - `table_name` string, required: The name of the table in the app
        - `table_mapping_id` string, required: The id shared by the two tables of a pair
        - `sync_direction` 'bidirectional' | 'incoming' | 'outgoing', required: The direction of the table
        - `columns` SyncSchemaColumn[], required: The synced columns
          - `column_name` string, required: The name of the column in the app, after renames
          - `column_mapping_id` string, required: The id shared by the two columns of a pair

## Other responses

- `400`: The body is not valid JSON or not an object; `base_id` in the body differs from the path (`Invalid Request`); a required field is missing, of the wrong type or not allowed (`Invalid Input`): `base_id`, `base_name`, `base_region`, two `apps` each with `app_id`, `connection_id` and `tables`; an `app_id` the sync does not hold; the apps, tables or columns do not pair; a table or column does not exist in its app; a rate limit or primary key is invalid; the sync does not exist (`Error editing base`: `Base not found`); the app refused the credentials or could not be reached; the edit failed (`Error editing base`)
- `403`: Forbidden: invalid API key, API key of another workspace, insufficient scope, workspace unavailable, or a non-GET request without `Content-Type: application/json`

---

[API](https://skmtc.dev/stacksync/apis/stacksync-api.md) - [All operations](https://skmtc.dev/stacksync/apis/stacksync-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacksync/apis/stacksync-api/revisions/21f4ba4b214e?raw)