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
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.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs/{org_slug}/app-data |
List apps |
| GET | /api/v1/orgs/{org_slug}/app-data/{app}/changes |
List changes |
| 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} |
One record |
| 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} |
Deletes the record |
List apps
Section titled List appsGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
List changes
Section titled List changesGET /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
Section titled 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
Section titled 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
Section titled The app's records in key order, without deleted or expired onesGET /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
Section titled 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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
One record
Section titled One recordGET /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
Section titled 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
Section titled 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
Section titled Writes the record: 201 when it creates it, 200 when it changes itPUT /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
Section titled 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
Section titled Request bodyapplication/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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Deletes the record
Section titled Deletes the recordDELETE /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
Section titled 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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |