# Edit a sync

> 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.

Source: https://docs.stacksync.com/api-reference/syncs/edit_sync

`PUT https://api.stacksync.com/v1/workspaces/{workspace_id}/bases/{base_id}`

- Operation: `edit_sync`
- Resource: Syncs
- Access: writes data

## Authentication

- `Authorization: Bearer <key>`: A workspace API key (workspace_…, created by a workspace owner under Workspace settings > Stacksync API) acts with editor rights on that workspace only; a user API key (user_…, created under Profile > Stacksync API) acts as that user in every workspace they belong to. POST, PUT and PATCH requests must send Content-Type: application/json. Every authentication failure answers 403.
- `Content-Type: application/json` on every request with a body.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | The workspace the resources belong to |
| `base_id` | string (uuid) | Yes | The sync (a sync is called a base in these paths) |

## Request body

`application/json`. The whole sync after the edit

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `base_id` | string (uuid) | Yes | The sync; must equal the `base_id` of the path |
| `base_name` | string | Yes | The name of the sync |
| `base_region` | string (besg \| usnv) | Yes | The data region of the sync |
| `apps` | array of object (SyncAppEditInput), exactly 2 items | Yes | Exactly two apps, with their `app_id` |
| `apps[].app_id` | string | Yes | The app's id in the sync (read it from the sync); an id the sync does not hold is refused |
| `apps[].connection_id` | string (uuid) | Yes | The connection of the app; the user of the API key must have created it or it must be shared with the workspace |
| `apps[].tables` | array of object (SyncTableEditInput), at least 1 item | Yes | 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 |
| `apps[].tables[].table_name` | string | Yes | 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 |
| `apps[].tables[].table_mapping_id` | string (uuid) | Yes | A UUID you choose, the same for the two tables of a pair and different from every other mapping id |
| `apps[].tables[].sync_direction` | string (bidirectional \| incoming \| outgoing) | Yes | `bidirectional` (paired with `bidirectional`), `incoming` (only written into, paired with `outgoing`) or `outgoing` (only read from, paired with `incoming`) |
| `apps[].tables[].table_options` | object (SyncTableOptionsInput) | No | The options of a table in the sync |
| `apps[].tables[].table_options.create_new_table` | boolean | Yes | 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 |
| `apps[].tables[].table_options.primary_key` | object (SyncPrimaryKeyInput) | No | The primary key column of a table being created, instead of the default `stacksync_record_id_` of type uuid (Postgres apps only) |
| `apps[].tables[].table_options.primary_key.column_name` | string | Yes | The name of the primary key column: letters, numbers and underscores, at most 63 characters, not a synced column's name |
| `apps[].tables[].table_options.primary_key.data_type` | string (uuid \| text \| varchar), default "uuid" | No | The type of the column |
| `apps[].tables[].columns` | array of object (SyncColumnInput) | No | 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 |
| `apps[].tables[].columns[].column_name` | string | Yes | 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 |
| `apps[].tables[].columns[].column_mapping_id` | string (uuid) | Yes | A UUID you choose, the same for the two columns of a pair and different from every other mapping id |
| `apps[].rate_limit` | object (SyncRateLimit) | No | The most requests Stacksync makes to the app in a period |
| `apps[].rate_limit.rate` | integer, 1 to 2147483647 | Yes | The number of requests allowed per period, 1 to 2147483647 |
| `apps[].rate_limit.frequency` | integer (1 \| 60 \| 3600 \| 86400) | Yes | The period of the rate in seconds: 1 (per second), 60 (per minute), 3600 (per hour) or 86400 (per day) |
| `apps[].app_options` | object (SyncAppOptionsInput) | No | The options of an app in the sync |
| `apps[].app_options.delete_protection` | boolean, default false | No | True to keep deletes from reaching this app (set on every table of the app) |
| `base_resource_id` | string, pattern `^[A-Za-z0-9_]{1,60}$` | No | The stable id of the sync |
| `base_status` | string | No | Accepted and stored as given; leave it out |
| `validate_only` | boolean, default false | No | Run every check of the edit, including reading the apps, and answer the sync as it would be stored without changing it |

## Returns

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

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

## Example request

```bash
curl -X PUT "https://api.stacksync.com/v1/workspaces/{workspace_id}/bases/{base_id}" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "base_id": "3f6c1d2e-8a4b-4c7d-9e21-5b6f7a8c9d01",
  "base_name": "Salesforce accounts to Postgres",
  "base_region": "usnv",
  "apps": [
    {
      "app_id": "3f9a1c2e",
      "connection_id": "c7d8e9f0-2a3b-4c5d-9e6f-7a8b9c0d1e2f",
      "tables": [
        {
          "table_name": "Account",
          "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
          "sync_direction": "outgoing",
          "columns": [
            {
              "column_name": "Name",
              "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
            }
          ]
        }
      ]
    },
    {
      "app_id": "b71d04e5",
      "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
      "tables": [
        {
          "table_name": "accounts",
          "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
          "sync_direction": "incoming",
          "columns": [
            {
              "column_name": "name",
              "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
            }
          ]
        }
      ]
    }
  ]
}'
```

## Example response (200)

```json
{
  "data": {
    "base_id": "3f6c1d2e-8a4b-4c7d-9e21-5b6f7a8c9d01",
    "base_name": "Salesforce accounts to Postgres",
    "base_region": "usnv",
    "base_resource_id": "salesforce_accounts_to_postgres",
    "apps": [
      {
        "app_id": "3f9a1c2e",
        "connection_id": "c7d8e9f0-2a3b-4c5d-9e6f-7a8b9c0d1e2f",
        "tables": [
          {
            "table_name": "Account",
            "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
            "sync_direction": "outgoing",
            "columns": [
              {
                "column_name": "Name",
                "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
              }
            ]
          }
        ]
      },
      {
        "app_id": "b71d04e5",
        "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
        "tables": [
          {
            "table_name": "accounts",
            "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
            "sync_direction": "incoming",
            "columns": [
              {
                "column_name": "name",
                "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 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`) | `{ "error": string }` |
| 403 | Forbidden: invalid API key, API key of another workspace, insufficient scope, workspace unavailable, or a non-GET request without `Content-Type: application/json` | `{ "error": string }` |

## Related

- [API Reference overview](https://docs.stacksync.com/api-reference): base URLs, regions, pagination, idempotency and errors
- [Authentication](https://docs.stacksync.com/api-reference/authentication): API keys and the 403 answers
- OpenAPI document: https://docs.stacksync.com/openapi.json
- [List syncs](https://docs.stacksync.com/api-reference/syncs/list_syncs)
- [Get a sync](https://docs.stacksync.com/api-reference/syncs/get_sync)
- [Get the status of a sync](https://docs.stacksync.com/api-reference/syncs/get_sync_status)
- [Get sync metrics](https://docs.stacksync.com/api-reference/syncs/get_sync_metrics)
- [Get sync diagnostics](https://docs.stacksync.com/api-reference/syncs/get_sync_diagnostics)
- [Create a sync](https://docs.stacksync.com/api-reference/syncs/create_sync)
- [Update sync settings](https://docs.stacksync.com/api-reference/syncs/update_sync_settings)
- [Delete a sync](https://docs.stacksync.com/api-reference/syncs/delete_sync)
- [Rename a sync](https://docs.stacksync.com/api-reference/syncs/rename_sync)
- [Switch a sync on or off](https://docs.stacksync.com/api-reference/syncs/switch_sync)
- [Set the change capture method](https://docs.stacksync.com/api-reference/syncs/set_sync_app_cdc_method)
- [Set the rate limit of an app](https://docs.stacksync.com/api-reference/syncs/set_sync_app_rate_limit)
- [Set Salesforce Bulk API access](https://docs.stacksync.com/api-reference/syncs/set_sync_app_bulk_api_access)
- [Set delete protection of an app](https://docs.stacksync.com/api-reference/syncs/set_sync_app_delete_protection)