# Backend data API

The REST API your own apps and sites call with a project key (qk_pub_… or qk_sec_…), not a session. 10 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/backend-data-api/

10 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​projects/​{projectId}/​rest/​{table}`](#get-v1-projects-projectid-rest-table) | List rows the caller may see |
| [[POST]] | [`/​v1/​projects/​{projectId}/​rest/​{table}`](#post-v1-projects-projectid-rest-table) | Insert one row or up to 500 (all or nothing; rows:write, and a rule for the caller) |
| [[PATCH]] | [`/​v1/​projects/​{projectId}/​rest/​{table}`](#patch-v1-projects-projectid-rest-table) | Update every row matching ≥ 1 filter (rows:write, and a rule for the caller) |
| [[DELETE]] | [`/​v1/​projects/​{projectId}/​rest/​{table}`](#delete-v1-projects-projectid-rest-table) | Delete every row matching ≥ 1 filter (rows:write, and a rule for the caller) |
| [[GET]] | [`/​v1/​projects/​{projectId}/​rest/​{table}/​{id}`](#get-v1-projects-projectid-rest-table-id) | One row |
| [[PATCH]] | [`/​v1/​projects/​{projectId}/​rest/​{table}/​{id}`](#patch-v1-projects-projectid-rest-table-id) | Update one row (rows:write, and a rule for the caller) |
| [[DELETE]] | [`/​v1/​projects/​{projectId}/​rest/​{table}/​{id}`](#delete-v1-projects-projectid-rest-table-id) | Delete one row (rows:write, and a rule for the caller) |
| [[GET]] | [`/​v1/​projects/​{projectId}/​schema`](#get-v1-projects-projectid-schema) | Tables and typed columns the caller may use (a visitor or signed-in person sees only what the rules give them) |
| [[POST]] | [`/​v1/​projects/​{projectId}/​schema/​tables`](#post-v1-projects-projectid-schema-tables) | Create a table (secret key with schema:write; it starts private) |
| [[POST]] | [`/​v1/​projects/​{projectId}/​schema/​tables/​{table}/​columns`](#post-v1-projects-projectid-schema-tables-table-columns) | Add a column (secret key with schema:write) |

## Reference

### [[GET]] `/v1/projects/{projectId}/rest/{table}`

List rows the caller may see.

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |

**Response 200**: Rows

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/projects/{projectId}/rest/{table}`

Insert one row or up to 500 (all or nothing; rows:write, and a rule for the caller).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |

**Request body** (`application/json`)

An empty object: `{}`.

**Response 201**: Inserted row(s)

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PATCH]] `/v1/projects/{projectId}/rest/{table}`

Update every row matching ≥ 1 filter (rows:write, and a rule for the caller).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |

**Request body** (`application/json`)

An empty object: `{}`.

**Response 200**: Updated

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/projects/{projectId}/rest/{table}`

Delete every row matching ≥ 1 filter (rows:write, and a rule for the caller).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |

**Response 200**: Deleted

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/projects/{projectId}/rest/{table}/{id}`

One row.

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |
| `id` | path | string | yes | Row id |

**Response 200**: Row

A map of any or null.

Errors: `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PATCH]] `/v1/projects/{projectId}/rest/{table}/{id}`

Update one row (rows:write, and a rule for the caller).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |
| `id` | path | string | yes | Row id |

**Request body** (`application/json`)

An empty object: `{}`.

**Response 200**: Updated

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/projects/{projectId}/rest/{table}/{id}`

Delete one row (rows:write, and a rule for the caller).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |
| `id` | path | string | yes | Row id |

**Response 200**: Deleted

A map of any or null[].

Errors: `400`, `401`, `403`, `404`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/projects/{projectId}/schema`

Tables and typed columns the caller may use (a visitor or signed-in person sees only what the rules give them).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |

**Response 200**: Schema

| Field | Type | Required | Notes |
|---|---|---|---|
| `tables` | object[] | yes |  |
| `tables[].name` | string | yes |  |
| `tables[].columns` | object[] | yes | up to 66 items |
| `tables[].publicRead` | boolean | yes |  |
| `tables[].rules` | object[] | yes | up to 16 items |
| `tables[].rowCount` | integer or null | yes | at least 0 |
| `tables[].createdAt` | string (date-time) | yes |  |

Errors: `401`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/projects/{projectId}/schema/tables`

Create a table (secret key with schema:write; it starts private).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes |  |
| `columns` | object[] |  | up to 64 items. default |
| `columns[].name` | string | yes |  |
| `columns[].type` | "text" · "integer" · "real" · "boolean" · "timestamp" · "json" | yes |  |
| `columns[].nullable` | boolean |  | default true |
| `publicRead` | boolean |  | default false |
| `confirmPublic` | string |  |  |

**Response 201**: Created

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes |  |
| `columns` | object[] | yes | up to 66 items |
| `columns[].name` | string | yes |  |
| `columns[].type` | "text" · "integer" · "real" · "boolean" · "timestamp" · "json" | yes |  |
| `columns[].nullable` | boolean | yes |  |
| `columns[].system` | boolean | yes |  |
| `publicRead` | boolean | yes |  |
| `rules` | object[] | yes | up to 16 items |
| `rules[].id` | string | yes |  |
| `rules[].audience` | object | yes |  |
| `rules[].actions` | "read" · "insert" · "update" · "delete"[] | yes | up to 4 items |
| `rules[].where` | object | yes |  |
| `rules[].columns` | string[] or null | yes | up to 66 items |
| `rules[].migrated` | boolean |  |  |
| `rules[].sentence` | string | yes | up to 400 characters |
| `rowCount` | integer or null | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |

Errors: `400`, `401`, `403`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/projects/{projectId}/schema/tables/{table}/columns`

Add a column (secret key with schema:write).

- **Authentication:** a project key (`qk_pub_…` or `qk_sec_…`) as `Authorization: Bearer`.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `projectId` | path | string | yes | Backend project id. 1 to 128 characters |
| `table` | path | string | yes | Table name. 1 to 48 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes |  |
| `type` | "text" · "integer" · "real" · "boolean" · "timestamp" · "json" | yes |  |
| `nullable` | boolean |  | default true |

**Response 201**: Table

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes |  |
| `columns` | object[] | yes | up to 66 items |
| `columns[].name` | string | yes |  |
| `columns[].type` | "text" · "integer" · "real" · "boolean" · "timestamp" · "json" | yes |  |
| `columns[].nullable` | boolean | yes |  |
| `columns[].system` | boolean | yes |  |
| `publicRead` | boolean | yes |  |
| `rules` | object[] | yes | up to 16 items |
| `rules[].id` | string | yes |  |
| `rules[].audience` | object | yes |  |
| `rules[].actions` | "read" · "insert" · "update" · "delete"[] | yes | up to 4 items |
| `rules[].where` | object | yes |  |
| `rules[].columns` | string[] or null | yes | up to 66 items |
| `rules[].migrated` | boolean |  |  |
| `rules[].sentence` | string | yes | up to 400 characters |
| `rowCount` | integer or null | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).