Run and integrate
API reference
Every public endpoint, grouped by resource, from the API's OpenAPI schema.
On this page
The DOGM API is what the web app and the GitHub Action's hosted mode call. It's JSON over HTTPS at https://api.dogm.ai. Everything below is rendered from the API's OpenAPI schema (DOGM.ai API 0.1.0), so it lists the endpoints and fields the code actually has.
Authentication#
Every /v1/* request sends a bearer token, and there are two kinds:
- A WorkOS session token. The web app signs you in with WorkOS AuthKit and sends your access token. Requests that act in an org also send
X-Org-Idwith an org ID fromGET /v1/me; without it they get400 E_ORG_HEADER. - A project API key,
dogm_live_and 52 more characters, for CI and scripts. Create one under Settings > API keys (orPOST /v1/api-keys). It's shown once, belongs to one project, and carries scopes:specs:read,runs:read,runs:write. A key needs noX-Org-Id, because it names its own org and acts as a member of its project. Only the endpoints marked with a scope below accept keys.
curl https://api.dogm.ai/v1/runs?project_id=$PROJECT_ID \
-H "Authorization: Bearer $DOGM_API_KEY"
On Free, API keys are paused: requests with one get 402 E_KEY_PAUSED. A missing scope is 403 E_SCOPE.
Errors#
Every error body has the same shape. The code is stable and meant for programs; the message is for people.
{ "detail": { "code": "E_SCOPE", "message": "this API key lacks the runs:write scope" } }Validation errors are 422 E_VALIDATION and add fields, a list of { path, message }. A 500 adds request_id. Every response carries an X-Request-Id header; send your own (letters, digits, ., _, -, up to 128 characters) to trace a request end to end.
Rate limits#
An API key makes at most 60 requests a minute. Signed-in users can burst 30 writes (POST, PUT, PATCH, DELETE), then 30 a minute; requests without credentials are limited per IP. Over a limit, the API answers 429 E_RATE_LIMIT with Retry-After.
Idempotent runs#
POST /v1/runs accepts an Idempotency-Key header. Retrying with the same key in the same org returns the existing run with 200 instead of starting a second one, so a CI job can retry safely.
Account and orgs#
The signed-in user, their orgs, and the current org.
Me#
GET/v1/me
Auth: Session token.
Responses: 200 Me. Errors use the shape in Errors.
Fields of Me
| Field | Type | Description |
|---|---|---|
userrequired | MeUser | |
orgsrequired | list of MeOrg | |
bannerrequired | Banner |
Create org#
POST/v1/orgs
Auth: Session token.
Request body: OrgCreate
| Field | Type | Description |
|---|---|---|
namerequired | string | |
locale | string | Default "en-PH" |
Responses: 201 Org. Errors use the shape in Errors.
Fields of Org
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
localerequired | string | |
planrequired | string | |
effective_planrequired | string | |
rolerequired | owner | admin | member | read_only | |
member_limitrequired | integer | |
created_atrequired | string (date-time) |
Get current org#
GET/v1/orgs/current
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Org. Errors use the shape in Errors.
Fields of Org
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
localerequired | string | |
planrequired | string | |
effective_planrequired | string | |
rolerequired | owner | admin | member | read_only | |
member_limitrequired | integer | |
created_atrequired | string (date-time) |
Update current org#
PATCH/v1/orgs/current
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: OrgUpdate
| Field | Type | Description |
|---|---|---|
name | string | |
locale | string |
Responses: 200 Org. Errors use the shape in Errors.
Fields of Org
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
localerequired | string | |
planrequired | string | |
effective_planrequired | string | |
rolerequired | owner | admin | member | read_only | |
member_limitrequired | integer | |
created_atrequired | string (date-time) |
Members#
People in the current org and their roles.
List members#
GET/v1/members
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Member. Errors use the shape in Errors.
Fields of Member
| Field | Type | Description |
|---|---|---|
user_idrequired | string (uuid) | |
emailrequired | string | |
namerequired | string | |
rolerequired | owner | admin | member | read_only | |
joined_atrequired | string (date-time) |
Change role#
PATCH/v1/members/{user_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
user_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: RoleChange
| Field | Type | Description |
|---|---|---|
rolerequired | admin | member | read_only |
Responses: 200 Member. Errors use the shape in Errors.
Fields of Member
| Field | Type | Description |
|---|---|---|
user_idrequired | string (uuid) | |
emailrequired | string | |
namerequired | string | |
rolerequired | owner | admin | member | read_only | |
joined_atrequired | string (date-time) |
Remove member#
DELETE/v1/members/{user_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
user_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Transfer ownership#
POST/v1/members/transfer-ownership
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: Transfer
| Field | Type | Description |
|---|---|---|
user_idrequired | string (uuid) |
Responses: 200 Member. Errors use the shape in Errors.
Fields of Member
| Field | Type | Description |
|---|---|---|
user_idrequired | string (uuid) | |
emailrequired | string | |
namerequired | string | |
rolerequired | owner | admin | member | read_only | |
joined_atrequired | string (date-time) |
Invites#
Invite by email; invites expire after 7 days.
List invites#
GET/v1/invites
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Invite. Errors use the shape in Errors.
Fields of Invite
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
emailrequired | string | |
rolerequired | admin | member | read_only | |
statusrequired | pending | accepted | revoked | expired | |
invited_byrequired | UserRef | |
expires_atrequired | string (date-time) | |
created_atrequired | string (date-time) |
Create invite#
POST/v1/invites
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: InviteCreate
| Field | Type | Description |
|---|---|---|
emailrequired | string | |
role | admin | member | read_only | Default "member" |
Responses: 201 InviteCreated. Errors use the shape in Errors.
Fields of InviteCreated
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
emailrequired | string | |
rolerequired | admin | member | read_only | |
statusrequired | pending | accepted | revoked | expired | |
invited_byrequired | UserRef | |
expires_atrequired | string (date-time) | |
created_atrequired | string (date-time) | |
invite_urlrequired | string | |
email_queuedrequired | bool |
Revoke invite#
DELETE/v1/invites/{invite_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
invite_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Accept invite#
POST/v1/invites/accept
Auth: Session token.
Request body: AcceptBody
| Field | Type | Description |
|---|---|---|
tokenrequired | string |
Responses: 200 Accepted. Errors use the shape in Errors.
Fields of Accepted
| Field | Type | Description |
|---|---|---|
org_idrequired | string (uuid) | |
rolerequired | admin | member | read_only |
Projects#
Projects group specs, runs and API keys.
List projects#
GET/v1/projects
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Project. Errors use the shape in Errors.
Fields of Project
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
default_localerequired | string | |
ai_samplesrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Create project#
POST/v1/projects
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: ProjectCreate
| Field | Type | Description |
|---|---|---|
namerequired | string | |
default_locale | string | Default "en-PH" |
ai_samples | bool | Default false |
Responses: 201 Project. Errors use the shape in Errors.
Fields of Project
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
default_localerequired | string | |
ai_samplesrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Get project#
GET/v1/projects/{project_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Project. Errors use the shape in Errors.
Fields of Project
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
default_localerequired | string | |
ai_samplesrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Update project#
PATCH/v1/projects/{project_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: ProjectUpdate
| Field | Type | Description |
|---|---|---|
name | string | |
default_locale | string | |
ai_samples | bool |
Responses: 200 Project. Errors use the shape in Errors.
Fields of Project
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
namerequired | string | |
default_localerequired | string | |
ai_samplesrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Delete project#
DELETE/v1/projects/{project_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Specs#
Specs, their versions, drafts and approval. Readable with an API key that has specs:read.
List templates#
GET/v1/templates
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Template. Errors use the shape in Errors.
Fields of Template
| Field | Type | Description |
|---|---|---|
templaterequired | string | |
namerequired | string | |
summaryrequired | string | |
source_yamlrequired | string |
List specs#
GET/v1/projects/{project_id}/specs
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Spec. Errors use the shape in Errors.
Fields of Spec
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string |
Create spec#
POST/v1/projects/{project_id}/specs
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: SpecCreate
| Field | Type | Description |
|---|---|---|
namerequired | string | |
source_yamlrequired | string |
Responses: 201 SpecDetail. Errors use the shape in Errors.
Fields of SpecDetail
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string | |
versionsrequired | list of VersionSummary |
Create spec from template#
POST/v1/projects/{project_id}/specs:from-template
Templates are curated, so v1 is approved on creation, for members too (CONTRACT-phase3.md, question 1).
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: SpecFromTemplate
| Field | Type | Description |
|---|---|---|
templaterequired | string | |
name | string |
Responses: 201 SpecDetail. Errors use the shape in Errors.
Fields of SpecDetail
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string | |
versionsrequired | list of VersionSummary |
Get spec#
GET/v1/specs/{spec_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 SpecDetail. Errors use the shape in Errors.
Fields of SpecDetail
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string | |
versionsrequired | list of VersionSummary |
Rename spec#
PATCH/v1/specs/{spec_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: SpecRename
| Field | Type | Description |
|---|---|---|
namerequired | string |
Responses: 200 SpecDetail. Errors use the shape in Errors.
Fields of SpecDetail
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string | |
versionsrequired | list of VersionSummary |
Delete spec#
DELETE/v1/specs/{spec_id}
Deletes the spec and its versions; refused while runs reference a version (they keep it reproducible).
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Get version#
GET/v1/specs/{spec_id}/versions/{number}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
numberrequired | path | integer | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 Version. Errors use the shape in Errors.
Fields of Version
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
numberrequired | integer | |
parent_version_idrequired | string (uuid) | |
statusrequired | draft | needs_review | approved | failed | |
spec_hashrequired | string | |
created_byrequired | UserRef | |
approved_byrequired | UserRef | |
approved_atrequired | string (date-time) | |
created_atrequired | string (date-time) | |
source_yamlrequired | string | |
spec_jsonrequired | object | |
compile_errorsrequired | list of CompileError | |
planrequired | Plan |
Save draft#
PUT/v1/specs/{spec_id}/draft
Edits the open version in place, or starts version n+1 (parent: n) when the latest is approved.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: DraftUpdate
| Field | Type | Description |
|---|---|---|
source_yamlrequired | string |
Responses: 200 Version. Errors use the shape in Errors.
Fields of Version
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
numberrequired | integer | |
parent_version_idrequired | string (uuid) | |
statusrequired | draft | needs_review | approved | failed | |
spec_hashrequired | string | |
created_byrequired | UserRef | |
approved_byrequired | UserRef | |
approved_atrequired | string (date-time) | |
created_atrequired | string (date-time) | |
source_yamlrequired | string | |
spec_jsonrequired | object | |
compile_errorsrequired | list of CompileError | |
planrequired | Plan |
Approve version#
POST/v1/specs/{spec_id}/versions/{number}:approve
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
numberrequired | path | integer | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Version. Errors use the shape in Errors.
Fields of Version
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
numberrequired | integer | |
parent_version_idrequired | string (uuid) | |
statusrequired | draft | needs_review | approved | failed | |
spec_hashrequired | string | |
created_byrequired | UserRef | |
approved_byrequired | UserRef | |
approved_atrequired | string (date-time) | |
created_atrequired | string (date-time) | |
source_yamlrequired | string | |
spec_jsonrequired | object | |
compile_errorsrequired | list of CompileError | |
planrequired | Plan |
AI drafting#
Draft a spec from a description or schema, suggest PII labels, and explain a failed check.
Compile spec#
POST/v1/projects/{project_id}/specs:compile
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: CompileRequest
| Field | Type | Description |
|---|---|---|
namerequired | string | |
input_kindrequired | describe | ddl | prisma | |
inputrequired | string |
Responses: 201 SpecDetail. Errors use the shape in Errors.
Fields of SpecDetail
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
templaterequired | string | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
latest_versionrequired | integer | |
latest_statusrequired | draft | needs_review | approved | failed | |
approved_versionrequired | integer | |
approved_hashrequired | string | |
versionsrequired | list of VersionSummary |
Get draft#
GET/v1/specs/{spec_id}/versions/{number}/ai
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
numberrequired | path | integer | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 AiDraft. Errors use the shape in Errors.
Fields of AiDraft
| Field | Type | Description |
|---|---|---|
spec_idrequired | string (uuid) | |
numberrequired | integer | |
statusrequired | draft | needs_review | approved | failed | |
source_kindrequired | yaml | describe | ddl | prisma | template | |
source_inputrequired | string | |
steprequired | queued | drafting | checking | repairing | classifying | done | |
attemptsrequired | integer | |
repairsrequired | integer | |
max_repairsrequired | integer | |
explanationrequired | string | |
piirequired | list of Pii |
Update PII#
PATCH/v1/specs/{spec_id}/versions/{number}/pii
Confirms each listed column's PII type and mask mode (as suggested, or changed). Only while it needs review.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
spec_idrequired | path | string (uuid) | |
numberrequired | path | integer | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: PiiPatch
| Field | Type | Description |
|---|---|---|
columnsrequired | list of PiiChange |
Responses: 200 AiDraft. Errors use the shape in Errors.
Fields of AiDraft
| Field | Type | Description |
|---|---|---|
spec_idrequired | string (uuid) | |
numberrequired | integer | |
statusrequired | draft | needs_review | approved | failed | |
source_kindrequired | yaml | describe | ddl | prisma | template | |
source_inputrequired | string | |
steprequired | queued | drafting | checking | repairing | classifying | done | |
attemptsrequired | integer | |
repairsrequired | integer | |
max_repairsrequired | integer | |
explanationrequired | string | |
piirequired | list of Pii |
Explain check#
POST/v1/runs/{run_id}/checks/{check_id}:explain
A failed check's fix suggestion, made by the model once and then served from storage. At most MAX_EXPLANATIONS checks of one run are explained (429 E_EXPLAIN_LIMIT). No connection is held while Claude answers: one session reads, the call runs, another session stores.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string (uuid) | |
check_idrequired | path | string | |
X-Org-Idrequired | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Explanation. Errors use the shape in Errors.
Fields of Explanation
| Field | Type | Description |
|---|---|---|
run_idrequired | string (uuid) | |
check_idrequired | string | |
explanationrequired | string | |
modelrequired | string | |
cachedrequired | bool | |
created_atrequired | string (date-time) |
Runs#
Start, list, cancel and download hosted runs, and read usage.
Create run#
POST/v1/runs
201 with the new run; 200 with the existing one when this Idempotency-Key was already used in the org.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Request body: RunCreate
| Field | Type | Description |
|---|---|---|
spec_version_idrequired | string (uuid) | |
seed | integer | Random when omitted. A number or a decimal string (above 2**53). |
rows | map of integer | |
format | csv | jsonl | sql | parquet | Default "csv" |
mask | bool | Default false |
spec_hash | string | The hash the caller expects; 409 E_SPEC_HASH_MISMATCH, uncounted, if not. |
Responses: 201 Run. Errors use the shape in Errors.
Fields of Run
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
spec_idrequired | string (uuid) | |
spec_version_idrequired | string (uuid) | |
spec_versionrequired | integer | |
spec_hashrequired | string | |
statusrequired | queued | running | succeeded | failed | cancelled | error | |
steprequired | plan | generate | finalize | combine | complete | |
progressrequired | Progress | |
seedrequired | string | |
rowsrequired | map of integer | |
formatrequired | csv | jsonl | sql | parquet | |
maskrequired | bool | |
mask_key_versionrequired | integer | |
engine_versionrequired | string | |
output_sha256required | string | |
checks_passedrequired | integer | |
checks_totalrequired | integer | |
errorrequired | RunError | |
started_byrequired | UserRef | |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
duration_msrequired | integer | |
expires_atrequired | string (date-time) | |
row_countsrequired | map of integer | |
checksrequired | list of Check | |
artifactsrequired | list of Artifact | |
reproducerequired | Reproduce |
List runs#
GET/v1/runs
Newest first. Pass next_cursor back as cursor for the next page; it is null on the last one.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id | query | string (uuid) | |
status | query | queued | running | succeeded | failed | cancelled | error | |
from | query | string (date-time) | Created at or after (ISO 8601). |
to | query | string (date-time) | Created before (ISO 8601). |
cursor | query | string | |
limit | query | integer | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 RunPage. Errors use the shape in Errors.
Fields of RunPage
| Field | Type | Description |
|---|---|---|
itemsrequired | list of RunSummary | |
next_cursorrequired | string |
Get run#
GET/v1/runs/{run_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 Run. Errors use the shape in Errors.
Fields of Run
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
spec_idrequired | string (uuid) | |
spec_version_idrequired | string (uuid) | |
spec_versionrequired | integer | |
spec_hashrequired | string | |
statusrequired | queued | running | succeeded | failed | cancelled | error | |
steprequired | plan | generate | finalize | combine | complete | |
progressrequired | Progress | |
seedrequired | string | |
rowsrequired | map of integer | |
formatrequired | csv | jsonl | sql | parquet | |
maskrequired | bool | |
mask_key_versionrequired | integer | |
engine_versionrequired | string | |
output_sha256required | string | |
checks_passedrequired | integer | |
checks_totalrequired | integer | |
errorrequired | RunError | |
started_byrequired | UserRef | |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
duration_msrequired | integer | |
expires_atrequired | string (date-time) | |
row_countsrequired | map of integer | |
checksrequired | list of Check | |
artifactsrequired | list of Artifact | |
reproducerequired | Reproduce |
Cancel run#
POST/v1/runs/{run_id}:cancel
Members cancel their own runs; admins and owners cancel any; an API key cancels runs started with a key (in its project). Chunks already written stay until retention.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 Run. Errors use the shape in Errors.
Fields of Run
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
spec_idrequired | string (uuid) | |
spec_version_idrequired | string (uuid) | |
spec_versionrequired | integer | |
spec_hashrequired | string | |
statusrequired | queued | running | succeeded | failed | cancelled | error | |
steprequired | plan | generate | finalize | combine | complete | |
progressrequired | Progress | |
seedrequired | string | |
rowsrequired | map of integer | |
formatrequired | csv | jsonl | sql | parquet | |
maskrequired | bool | |
mask_key_versionrequired | integer | |
engine_versionrequired | string | |
output_sha256required | string | |
checks_passedrequired | integer | |
checks_totalrequired | integer | |
errorrequired | RunError | |
started_byrequired | UserRef | |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
duration_msrequired | integer | |
expires_atrequired | string (date-time) | |
row_countsrequired | map of integer | |
checksrequired | list of Check | |
artifactsrequired | list of Artifact | |
reproducerequired | Reproduce |
Download artifact#
GET/v1/runs/{run_id}/artifacts/{artifact_id}
A signed URL that works for 15 minutes, only after this org's read of the artifact row (RLS). Artifacts are downloadable once their run succeeded; parts of a run that didn't finish are left to retention.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string (uuid) | |
artifact_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org (user tokens only; a key names its own). |
Responses: 200 Download. Errors use the shape in Errors.
Fields of Download
| Field | Type | Description |
|---|---|---|
urlrequired | string | |
expires_atrequired | string (date-time) | |
namerequired | string | |
bytesrequired | integer | |
sha256required | string |
Get usage#
GET/v1/usage
This period's usage against the effective plan.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Usage. Errors use the shape in Errors.
Fields of Usage
| Field | Type | Description |
|---|---|---|
planrequired | string | |
effective_planrequired | string | |
periodrequired | string | |
period_ends_atrequired | string (date-time) | |
runsrequired | Meter | |
ai_draftsrequired | Meter | |
storage_bytesrequired | Meter | |
concurrent_runsrequired | Meter | |
rows_per_runrequired | integer | |
retention_daysrequired | integer |
Billing#
The plan and period, QR Ph payments, acknowledgements and downgrades.
Create payment#
POST/v1/billing/payments
Owners. Returns the org's pending payment for this plan while its QR is still valid (200), else abandons any pending payment and creates a new one with a fresh QR code (201).
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Idrequired | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: PaymentCreate
| Field | Type | Description |
|---|---|---|
planrequired | pro | team |
Responses: 201 Payment. Errors use the shape in Errors.
Fields of Payment
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
planrequired | string | |
amount_centavosrequired | integer | |
currencyrequired | string | |
statusrequired | pending | succeeded | failed | abandoned | refunded | |
livemoderequired | bool | |
kindrequired | new | renewal | upgrade | downgrade | |
extra_daysrequired | integer | |
period_starts_atrequired | string (date-time) | |
period_ends_atrequired | string (date-time) | |
qr_image_urlrequired | string | |
qr_expires_atrequired | string (date-time) | |
test_urlrequired | string | |
failure_reasonrequired | string | |
created_atrequired | string (date-time) | |
paid_atrequired | string (date-time) | |
refunded_atrequired | string (date-time) |
Get payment#
GET/v1/billing/payments/{payment_id}
Owners; polled every 3 s by the pay screen. Answers from Postgres, asking PayMongo at most every 15 s.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
payment_idrequired | path | string (uuid) | |
X-Org-Idrequired | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Payment. Errors use the shape in Errors.
Fields of Payment
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
planrequired | string | |
amount_centavosrequired | integer | |
currencyrequired | string | |
statusrequired | pending | succeeded | failed | abandoned | refunded | |
livemoderequired | bool | |
kindrequired | new | renewal | upgrade | downgrade | |
extra_daysrequired | integer | |
period_starts_atrequired | string (date-time) | |
period_ends_atrequired | string (date-time) | |
qr_image_urlrequired | string | |
qr_expires_atrequired | string (date-time) | |
test_urlrequired | string | |
failure_reasonrequired | string | |
created_atrequired | string (date-time) | |
paid_atrequired | string (date-time) | |
refunded_atrequired | string (date-time) |
Refresh qr#
POST/v1/billing/payments/{payment_id}:refresh-qr
Owners. After the QR expires, attaches a new QR Ph payment method to the same Payment Intent. While the QR is still valid, returns the payment unchanged.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
payment_idrequired | path | string (uuid) | |
X-Org-Idrequired | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Payment. Errors use the shape in Errors.
Fields of Payment
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
planrequired | string | |
amount_centavosrequired | integer | |
currencyrequired | string | |
statusrequired | pending | succeeded | failed | abandoned | refunded | |
livemoderequired | bool | |
kindrequired | new | renewal | upgrade | downgrade | |
extra_daysrequired | integer | |
period_starts_atrequired | string (date-time) | |
period_ends_atrequired | string (date-time) | |
qr_image_urlrequired | string | |
qr_expires_atrequired | string (date-time) | |
test_urlrequired | string | |
failure_reasonrequired | string | |
created_atrequired | string (date-time) | |
paid_atrequired | string (date-time) | |
refunded_atrequired | string (date-time) |
Get billing#
GET/v1/billing
Owners: the plan, the period in effect, grace, a scheduled downgrade and the payment history.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Billing. Errors use the shape in Errors.
Fields of Billing
| Field | Type | Description |
|---|---|---|
planrequired | string | |
effective_planrequired | string | |
betarequired | bool | |
livemoderequired | bool | |
configuredrequired | bool | |
periodrequired | Period | |
next_periodrequired | Period | |
gracerequired | Grace | |
pending_planrequired | string | |
pricesrequired | map of integer | |
paymentsrequired | list of Payment |
Schedule downgrade#
POST/v1/billing/downgrade
Owners. Schedules a smaller plan for the next renewal (null cancels). The current period runs to its end; renewing with any plan settles it. free means the org won't renew.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: DowngradeSet
| Field | Type | Description |
|---|---|---|
planrequired | free | pro | team |
Responses: 200 Billing. Errors use the shape in Errors.
Fields of Billing
| Field | Type | Description |
|---|---|---|
planrequired | string | |
effective_planrequired | string | |
betarequired | bool | |
livemoderequired | bool | |
configuredrequired | bool | |
periodrequired | Period | |
next_periodrequired | Period | |
gracerequired | Grace | |
pending_planrequired | string | |
pricesrequired | map of integer | |
paymentsrequired | list of Payment |
Acknowledgement#
GET/v1/billing/payments/{payment_id}/acknowledgement
Owners: the printable payment acknowledgement (mvp.md 6.5). Not a BIR invoice.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
payment_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Acknowledgement. Errors use the shape in Errors.
Fields of Acknowledgement
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
org_namerequired | string | |
planrequired | string | |
plan_namerequired | string | |
amount_centavosrequired | integer | |
currencyrequired | string | |
statusrequired | string | |
livemoderequired | bool | |
test_noticerequired | string | |
disclaimerrequired | string | |
paid_atrequired | string (date-time) | |
period_starts_atrequired | string (date-time) | |
period_ends_atrequired | string (date-time) | |
refunded_atrequired | string (date-time) | |
referencerequired | string | |
paid_byrequired | UserRef |
Notifications#
Which emails the signed-in user gets.
Get notifications#
GET/v1/me/notifications
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 NotificationSettings. Errors use the shape in Errors.
Fields of NotificationSettings
| Field | Type | Description |
|---|---|---|
run_succeededrequired | bool | |
run_failedrequired | bool | |
spec_readyrequired | bool | |
usage_warningsrequired | bool |
Put notifications#
PUT/v1/me/notifications
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: NotificationSettings
| Field | Type | Description |
|---|---|---|
run_succeededrequired | bool | |
run_failedrequired | bool | |
spec_readyrequired | bool | |
usage_warningsrequired | bool |
Responses: 200 NotificationSettings. Errors use the shape in Errors.
Fields of NotificationSettings
| Field | Type | Description |
|---|---|---|
run_succeededrequired | bool | |
run_failedrequired | bool | |
spec_readyrequired | bool | |
usage_warningsrequired | bool |
API keys#
Project API keys for CI and scripts.
Create key#
POST/v1/api-keys
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: ApiKeyCreate
| Field | Type | Description |
|---|---|---|
project_idrequired | string (uuid) | |
namerequired | string | |
scopesrequired | list of specs:read | runs:read | runs:write |
Responses: 201 ApiKeyCreated. Errors use the shape in Errors.
Fields of ApiKeyCreated
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
prefixrequired | string | |
scopesrequired | list of specs:read | runs:read | runs:write | |
pausedrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
last_used_atrequired | string (date-time) | |
keyrequired | string |
List keys#
GET/v1/api-keys
Keys that aren't revoked, newest first.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id | query | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of ApiKey. Errors use the shape in Errors.
Fields of ApiKey
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
project_idrequired | string (uuid) | |
namerequired | string | |
prefixrequired | string | |
scopesrequired | list of specs:read | runs:read | runs:write | |
pausedrequired | bool | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
last_used_atrequired | string (date-time) |
Revoke key#
DELETE/v1/api-keys/{key_id}
Takes effect at once: the next request with the key gets 401 E_KEY_REVOKED.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
key_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Webhooks#
Endpoints, deliveries, test events and re-enabling.
Create webhook#
POST/v1/webhooks
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: WebhookCreate
| Field | Type | Description |
|---|---|---|
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review |
Responses: 201 WebhookCreated. Errors use the shape in Errors.
Fields of WebhookCreated
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review | |
statusrequired | active | disabled | paused | |
disabled_atrequired | string (date-time) | |
failing_sincerequired | string (date-time) | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
secretrequired | string |
List webhooks#
GET/v1/webhooks
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Webhook. Errors use the shape in Errors.
Fields of Webhook
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review | |
statusrequired | active | disabled | paused | |
disabled_atrequired | string (date-time) | |
failing_sincerequired | string (date-time) | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Get webhook#
GET/v1/webhooks/{webhook_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Webhook. Errors use the shape in Errors.
Fields of Webhook
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review | |
statusrequired | active | disabled | paused | |
disabled_atrequired | string (date-time) | |
failing_sincerequired | string (date-time) | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Update webhook#
PATCH/v1/webhooks/{webhook_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: WebhookUpdate
| Field | Type | Description |
|---|---|---|
url | string | |
events | list of run.succeeded | run.failed | spec.needs_review |
Responses: 200 Webhook. Errors use the shape in Errors.
Fields of Webhook
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review | |
statusrequired | active | disabled | paused | |
disabled_atrequired | string (date-time) | |
failing_sincerequired | string (date-time) | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Delete webhook#
DELETE/v1/webhooks/{webhook_id}
Deletes the endpoint and its deliveries; queued attempts find nothing and stop.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 204 Successful Response. Errors use the shape in Errors.
Enable webhook#
POST/v1/webhooks/{webhook_id}:enable
Re-enables an auto-disabled endpoint, with a clean failure record; a no-op on an enabled one.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 Webhook. Errors use the shape in Errors.
Fields of Webhook
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
urlrequired | string | |
eventsrequired | list of run.succeeded | run.failed | spec.needs_review | |
statusrequired | active | disabled | paused | |
disabled_atrequired | string (date-time) | |
failing_sincerequired | string (date-time) | |
created_byrequired | UserRef | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Test webhook#
POST/v1/webhooks/{webhook_id}:test
Queues a webhook.test event to this endpoint, whatever its events; watch its delivery for the result.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 202 Delivery. Errors use the shape in Errors.
Fields of Delivery
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
webhook_idrequired | string (uuid) | |
eventrequired | string | |
event_idrequired | string | |
payloadrequired | object | |
statusrequired | pending | succeeded | failed | |
response_coderequired | integer | |
attemptsrequired | integer | |
next_attempt_atrequired | string (date-time) | |
last_errorrequired | string | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
List deliveries#
GET/v1/webhooks/{webhook_id}/deliveries
The most recent first.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
limit | query | integer | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 200 list of Delivery. Errors use the shape in Errors.
Fields of Delivery
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
webhook_idrequired | string (uuid) | |
eventrequired | string | |
event_idrequired | string | |
payloadrequired | object | |
statusrequired | pending | succeeded | failed | |
response_coderequired | integer | |
attemptsrequired | integer | |
next_attempt_atrequired | string (date-time) | |
last_errorrequired | string | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Retry delivery#
POST/v1/webhooks/{webhook_id}/deliveries/{delivery_id}:retry
Sends a failed delivery again, with the same body id (receivers dedupe on it) and a fresh signature.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string (uuid) | |
delivery_idrequired | path | string (uuid) | |
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 202 Delivery. Errors use the shape in Errors.
Fields of Delivery
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
webhook_idrequired | string (uuid) | |
eventrequired | string | |
event_idrequired | string | |
payloadrequired | object | |
statusrequired | pending | succeeded | failed | |
response_coderequired | integer | |
attemptsrequired | integer | |
next_attempt_atrequired | string (date-time) | |
last_errorrequired | string | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
Export and deletion#
Export or delete your data and your org.
Delete me#
DELETE/v1/me
Deletes the caller's account, confirming with their email address. 409 E_SOLE_OWNER (with orgs) while they are the only owner of an org: transfer ownership or delete the org first.
Auth: Session token.
Request body: Confirm
| Field | Type | Description |
|---|---|---|
confirmrequired | string |
Responses: 204 Successful Response. Errors use the shape in Errors.
Delete org#
DELETE/v1/orgs/current
Owners, confirming with the org's exact name. Soft delete: restorable by staff for 7 days, then purged.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Request body: Confirm
| Field | Type | Description |
|---|---|---|
confirmrequired | string |
Responses: 200 OrgDeleted. Errors use the shape in Errors.
Fields of OrgDeleted
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
deleted_atrequired | string (date-time) | |
purge_onrequired | string (date-time) |
Export org#
POST/v1/orgs/current:export
Owners: the org's specs (every version's YAML), run metadata, members and payments as JSON; never artifacts.
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
X-Org-Id | header | string | The org this request acts in: an id from GET /v1/me. |
Responses: 202 Export. Errors use the shape in Errors.
Fields of Export
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
kindrequired | org | user | |
statusrequired | queued | ready | failed | expired | |
bytesrequired | integer | |
created_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
expires_atrequired | string (date-time) | |
urlrequired | string |
Export me#
POST/v1/me:export
The caller's profile, memberships and the audit entries they are the actor of, as JSON.
Auth: Session token.
Responses: 202 Export. Errors use the shape in Errors.
Fields of Export
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
kindrequired | org | user | |
statusrequired | queued | ready | failed | expired | |
bytesrequired | integer | |
created_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
expires_atrequired | string (date-time) | |
urlrequired | string |
Get export#
GET/v1/exports/{export_id}
Auth: Session token.
| Parameter | In | Type | Description |
|---|---|---|---|
export_idrequired | path | string (uuid) |
Responses: 200 Export. Errors use the shape in Errors.
Fields of Export
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
kindrequired | org | user | |
statusrequired | queued | ready | failed | expired | |
bytesrequired | integer | |
created_atrequired | string (date-time) | |
finished_atrequired | string (date-time) | |
expires_atrequired | string (date-time) | |
urlrequired | string |
Health#
Liveness and readiness, with no auth.
Healthz#
GET/healthz
Auth: No authentication.
Responses: 200 map of string. Errors use the shape in Errors.
Readyz#
GET/readyz
Ready for traffic: Postgres and object storage both answer within 3 seconds. 503 names what failed.
Auth: No authentication.
Responses: 200 any. Errors use the shape in Errors.
From the API's OpenAPI schema, committed as content/docs/generated/openapi.json. Staff-only admin endpoints and the payment provider's callback are left out.