# Create a sync

> Create a sync between two apps from the tables and columns you pair with mapping ids. Stacksync reads both apps, checks every table and column, creates the tables marked `create_new_table` and stores the sync switched off: switch it on with the switch route. Send `validate_only: true` to run every check and get the sync as it would be stored without creating it.

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

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

- Operation: `create_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 |

## Request body

`application/json`. The sync to create

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `base_name` | string | Yes | The name of the sync. 3 to 63 characters: unaccented letters (A-Z, a-z), numbers, underscores, dashes and spaces only; unique in the workspace |
| `base_region` | string (besg \| usnv) | Yes | The data region the sync runs in; the connections must be in it |
| `apps` | array of object (SyncAppInput), exactly 2 items | Yes | Exactly two apps |
| `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 (SyncTableInput), at least 1 item | Yes | The tables to sync, one per table pair; both apps list the same number of tables and the same `table_mapping_id`s |
| `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) | Yes | 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 | A stable id of your choosing, 1 to 60 letters, digits or underscores, unique in the workspace; derived from the name when left out |
| `base_status` | string | No | Accepted and stored as given; leave it out so Stacksync sets the state of the new sync itself |
| `folder_id` | string (uuid) | No | The folder of the workspace, in `base_region`, to file the sync under; the root when left out |
| `validate_only` | boolean, default false | No | Run every check of the create, including reading the apps, and answer the sync as it would be stored (its column names after renames, no `base_id`) without creating it |

## Returns

### 200 The sync created (with `validate_only`, the sync as it would be stored, without `base_id`)

| 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 POST "https://api.stacksync.com/v1/workspaces/{workspace_id}/bases" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "base_name": "Salesforce accounts to Postgres",
  "base_region": "usnv",
  "base_resource_id": "salesforce_accounts_to_postgres",
  "folder_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "apps": [
    {
      "connection_id": "c7d8e9f0-2a3b-4c5d-9e6f-7a8b9c0d1e2f",
      "tables": [
        {
          "table_name": "Account",
          "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
          "sync_direction": "bidirectional",
          "table_options": {
            "create_new_table": false
          },
          "columns": [
            {
              "column_name": "Name",
              "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
            },
            {
              "column_name": "Website",
              "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
            }
          ]
        }
      ],
      "rate_limit": {
        "rate": 50,
        "frequency": 1
      }
    },
    {
      "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
      "tables": [
        {
          "table_name": "accounts",
          "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
          "sync_direction": "bidirectional",
          "table_options": {
            "create_new_table": true,
            "primary_key": {
              "column_name": "account_id",
              "data_type": "text"
            }
          },
          "columns": [
            {
              "column_name": "name",
              "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
            },
            {
              "column_name": "website",
              "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
            }
          ]
        }
      ],
      "app_options": {
        "delete_protection": true
      }
    }
  ]
}'
```

## 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",
        "rate_limit": {
          "rate": 50,
          "frequency": 1
        },
        "tables": [
          {
            "table_name": "Account",
            "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
            "sync_direction": "bidirectional",
            "columns": [
              {
                "column_name": "Name",
                "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
              },
              {
                "column_name": "Website",
                "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
              }
            ]
          }
        ]
      },
      {
        "app_id": "b71d04e5",
        "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
        "tables": [
          {
            "table_name": "accounts",
            "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
            "sync_direction": "bidirectional",
            "columns": [
              {
                "column_name": "name",
                "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
              },
              {
                "column_name": "website",
                "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 400 | The body is not valid JSON; a required field is missing, of the wrong type or not allowed (`Invalid Request Body`, `Invalid Input`): `base_name`, `base_region`, `apps` with `connection_id` and `tables` of `table_name`, `table_mapping_id`, `sync_direction`, `table_options.create_new_table`; the name breaks the name rule; `base_resource_id` breaks its pattern; `folder_id` is not a folder of the workspace in the sync's region; the name or resource id is already taken (`Validation Error`); the apps are not two, the tables or columns do not pair (counts, mapping ids, directions, duplicates); a table or column does not exist in its app, a table to create already exists or its app cannot create tables, a rate limit or primary key is invalid; the app refused the credentials or could not be reached; the sync could not be created (`Error creating 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)
- [Update sync settings](https://docs.stacksync.com/api-reference/syncs/update_sync_settings)
- [Edit a sync](https://docs.stacksync.com/api-reference/syncs/edit_sync)
- [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)