# Get an app schema

> List the tables Stacksync can sync through a connection, with the primary key of each. Columns are not read by this route: use the generate app schema route with `table_names` to read them.

Source: https://docs.stacksync.com/api-reference/syncs/app-schema/get_app_schema

`GET https://api.stacksync.com/v1/workspaces/{workspace_id}/helpers/app-schema`

- Operation: `get_app_schema`
- Resource: App schema
- Access: read-only

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

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | The workspace the resources belong to |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string (besg \| usnv) | Yes | Data region of the connection |
| `connection_id` | string (uuid) | Yes | The connection to read the schema through; the user of the API key must have created it or it must be shared with the workspace |

## Returns

### 200 The tables of the app

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `app_type` | string | Yes | The app of the connection, as shown in Stacksync |
| `can_create_tables` | boolean | Yes | Whether a sync may create a new table in this app (`table_options.create_new_table: true`) |
| `tables` | array of object (AppSchemaTable) | Yes | Every table of the app |
| `tables[].table_name` | string | Yes | The name of the table in the app: the value to send as `table_name` when creating a sync (its id is accepted too) |
| `tables[].table_id` | string | Yes | The id of the table in the app, when the app has one apart from the name (BigQuery: `project.dataset.table`) |
| `tables[].table_options` | object (AppSchemaTableOptions) | Yes | The options of a table of the app |
| `tables[].table_options.primary_key` | object (AppSchemaPrimaryKey) | No | The primary key of a table |
| `tables[].table_options.primary_key.column_name` | string | No | The name of the primary key column |
| `tables[].table_options.primary_key.column_type` | string | No | The Stacksync type of the column (for example `string`, `int`, `uuid`, `datetime`) |
| `tables[].columns` | array of object (AppSchemaColumn) | Yes | The columns of the table; only filled for the tables named in `table_names`, empty for the others |
| `tables[].columns[].column_name` | string | Yes | The name of the column in the app: the value to send as `column_name` when creating a sync |
| `tables[].columns[].column_type` | string | Yes | The Stacksync type of the column (for example `string`, `int`, `number`, `boolean`, `datetime`, `uuid`, `json`) |
| `tables[].columns[].writable` | boolean | No | Whether a sync can write to the column; absent when the app does not say |

## Example request

```bash
curl -X GET "https://api.stacksync.com/v1/workspaces/{workspace_id}/helpers/app-schema?region=besg&connection_id=3f6c1d2e-8a4b-4c7d-9e21-5b6f7a8c9d01" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"
```

## Example response (200)

```json
{
  "app_type": "postgres",
  "can_create_tables": true,
  "tables": [
    {
      "table_name": "accounts",
      "table_id": "accounts",
      "table_options": {
        "primary_key": {
          "column_name": "id",
          "column_type": "uuid"
        }
      },
      "columns": []
    },
    {
      "table_name": "contacts",
      "table_id": "contacts",
      "table_options": {},
      "columns": []
    }
  ]
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 400 | The `region` is missing or not one of besg, usnv; `connection_id` is missing or not a UUID; the app does not support syncs (`App Not Supported`); the app refused the credentials (`Connection Authorization Error`); Stacksync could not connect to the app (`Connection Error`); the schema could not be read (`Error generating app schema`, `Error retrieving app schema`) | `{ "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 }` |
| 404 | The connection does not exist in the workspace and region, or is not visible to the user of the API key (`Error retrieving connection`) | `{ "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
- [Generate an app schema](https://docs.stacksync.com/api-reference/syncs/app-schema/generate_app_schema)