# Organization API: App data

> Records the organization's own apps keep in Coritan instead of a database: one JSON value per key, with a version for writes that must not overwrite each other, an optional expiry, the lowest role tha

Source: https://www.coritan.com/docs/api/reference/organizations/app-data/

Records the organization's own apps keep in Coritan instead of a database: one JSON value per key, with a version for writes that must not overwrite each other, an optional expiry, the lowest role that may change it, and a feed of what changed. A member's Bearer token; API keys are refused. Paths are under `/api/v1/orgs/{org_slug}/app-data`.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/app-data`](#op-get-api-v1-orgs-org-slug-app-data) | List apps |
| GET | [`/api/v1/orgs/{org_slug}/app-data/{app}/changes`](#op-get-api-v1-orgs-org-slug-app-data-app-changes) | List changes |
| GET | [`/api/v1/orgs/{org_slug}/app-data/{app}/records`](#op-get-api-v1-orgs-org-slug-app-data-app-records) | The app's records in key order, without deleted or expired ones |
| GET | [`/api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`](#op-get-api-v1-orgs-org-slug-app-data-app-records-key) | One record |
| PUT | [`/api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`](#op-put-api-v1-orgs-org-slug-app-data-app-records-key) | Writes the record: 201 when it creates it, 200 when it changes it |
| DELETE | [`/api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`](#op-delete-api-v1-orgs-org-slug-app-data-app-records-key) | Deletes the record |

### List apps {#op-get-api-v1-orgs-org-slug-app-data}

`GET /api/v1/orgs/{org_slug}/app-data`

Every app name the organization keeps data for, with how many records it holds (``records``),
how large their values are (``bytes``) and the number of its last change (``last_change``).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List changes {#op-get-api-v1-orgs-org-slug-app-data-app-changes}

`GET /api/v1/orgs/{org_slug}/app-data/{app}/changes`

Every record that changed after change number ``after``, in the order the changes were made, each
as it is now. Deleted records come with ``deleted: true`` and no value for 30 days after; a record
that expired comes as it was, so compare its ``expires_at`` with the time. Pass ``next_after`` back as
``after`` until ``more`` is false, then again later for what changed since: changes are numbered in
the order they are saved, so none is skipped.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app` | path | string | yes | The app's name: 2–40 lowercase letters, digits and hyphens, starting with a letter. You pick it; the first write makes it. |
| `org_slug` | path | string | yes |  |
| `after` | query | integer | no | The change number to start after: 0 for everything, then the `next_after` of the answer before. Default: `0`. |
| `prefix` | query | string or null | no | Only keys that start with this. |
| `limit` | query | integer | no | Default: `500`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The app's records in key order, without deleted or expired ones {#op-get-api-v1-orgs-org-slug-app-data-app-records}

`GET /api/v1/orgs/{org_slug}/app-data/{app}/records`

The app's records in key order, without deleted or expired ones. ``next_after`` is the key to
pass as ``after`` for the next page, or null on the last page.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app` | path | string | yes | The app's name: 2–40 lowercase letters, digits and hyphens, starting with a letter. You pick it; the first write makes it. |
| `org_slug` | path | string | yes |  |
| `prefix` | query | string or null | no | Only keys that start with this. |
| `after` | query | string or null | no | Start after this key: the `next_after` of the page before. |
| `limit` | query | integer | no | Default: `100`. |
| `values` | query | boolean | no | false to leave the values out and list keys and versions only. Default: `True`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One record {#op-get-api-v1-orgs-org-slug-app-data-app-records-key}

`GET /api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`

One record. 404 ``record_not_found`` when the key holds none, or the record was deleted or expired.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app` | path | string | yes | The app's name: 2–40 lowercase letters, digits and hyphens, starting with a letter. You pick it; the first write makes it. |
| `key` | path | string | yes | The record's key: 1–160 lowercase letters, digits and `. _ : @ / -`, starting with a letter or digit. Slashes group keys, as in `views/42`. |
| `org_slug` | path | string | yes |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Writes the record: 201 when it creates it, 200 when it changes it {#op-put-api-v1-orgs-org-slug-app-data-app-records-key}

`PUT /api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`

Writes the record: 201 when it creates it, 200 when it changes it. ``version`` makes the write
conditional, 409 ``version_conflict`` (with ``current_version``) when the record has moved on, so
two writers never overwrite each other unseen; ``version: 0`` with ``expires_in`` makes a lease or
a one-time claim. 403 ``role_required`` when the record's ``write_role`` is above your role, or you
ask for a ``write_role`` above it; 413 ``value_too_large`` past 256 KB; 409 ``limit_reached`` when
the app holds 20,000 records or 64 MB of values, or the organization 20 app names. Creating a record
is recorded in the organization's audit log; a change to one is not.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app` | path | string | yes | The app's name: 2–40 lowercase letters, digits and hyphens, starting with a letter. You pick it; the first write makes it. |
| `key` | path | string | yes | The record's key: 1–160 lowercase letters, digits and `. _ : @ / -`, starting with a letter or digit. Slashes group keys, as in `views/42`. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | Value | yes | Any JSON value, at most 256 KB once encoded. |
| `version` | integer or null | no | Write only if the record is at this version now; 0 to write only if the key holds no record. Leave it out to write whatever is there. |
| `write_role` | string or null | no | The lowest role that may change or delete the record, at most your own. A new record defaults to your role; a change keeps the record's. |
| `expires_in` | integer or null | no | Seconds until the record expires and reads as absent, from 10 to 366 days. Leave it out for a record that stays; each write sets it again. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Deletes the record {#op-delete-api-v1-orgs-org-slug-app-data-app-records-key}

`DELETE /api/v1/orgs/{org_slug}/app-data/{app}/records/{key}`

Deletes the record. It stays 30 days in the changes as ``deleted: true``, and the key can be
written again at once. 404 when there is no record, 409 ``version_conflict`` when ``version`` is
not the record's, 403 ``role_required`` below its ``write_role``. Recorded in the audit log.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app` | path | string | yes | The app's name: 2–40 lowercase letters, digits and hyphens, starting with a letter. You pick it; the first write makes it. |
| `key` | path | string | yes | The record's key: 1–160 lowercase letters, digits and `. _ : @ / -`, starting with a letter or digit. Slashes group keys, as in `views/42`. |
| `org_slug` | path | string | yes |  |
| `version` | query | integer or null | no | Delete only if the record is at this version now. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |