Token API (/v1)
Programmatic endpoints, authenticated with a Bearer token (a personal access token atx_pat_… or an OAuth token atx_oat_…).
Generated from the Atrix Analytics — control plane API OpenAPI document, version 0.1.0. 45 operations. The raw document is at /openapi.json.
GET /v1/erasure-certificates/keys
Auth: none.
| Status | Body | Notes |
|---|---|---|
| 200 | — | {keys: [{alg: Ed25519, kid, public_key}]}: the certificate verification keys |
POST /v1/erasure-certificates/verify
Auth: none.
Request body (application/json): VerifyRequest
| Field | Type | Required | Description |
|---|---|---|---|
certificate | object | yes | |
signature | string | yes | |
verify | object | null | The verify hint the certificate endpoint returns alongside; accepted (and ignored) so that endpoint's response can be posted here unchanged. |
| Status | Body | Notes |
|---|---|---|
| 200 | — | {valid, key_id, …}: whether the signature is ours over exactly this certificate |
| 400 | ErrorBody |
GET /v1/me
The calling token, its user, and its effective scopes.
Auth: Bearer token.
| Status | Body | Notes |
|---|---|---|
| 200 | V1MeResponse | |
| 401 | ErrorBody |
GET /v1/orgs
The org this token belongs to (org:read).
Auth: Bearer token with org:read.
GET /v1/orgs/{org_id}
Auth: Bearer token with org:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
org_id | path | string (uuid) | yes |
GET /v1/orgs/{org_id}/projects
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
org_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | ProjectList | |
| 404 | ErrorBody |
POST /v1/orgs/{org_id}/projects
Create a project (projects:write). ?dry_run=true validates and returns the plan.
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
org_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
Request body (application/json): CreateProjectRequest
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | null | ISO 4217, default USD. | |
name | string | yes | |
region | string | yes | Region code. Fixed for the life of the project. Only live regions are accepted. |
timezone | string | null | IANA zone, default UTC. |
| Status | Body | Notes |
|---|---|---|
| 200 | DryRun | dry_run |
| 201 | CreateProjectResponse | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 409 | ErrorBody | |
| 422 | ErrorBody |
GET /v1/projects
Projects this token can read (projects:read).
Auth: Bearer token with projects:read.
| Status | Body | Notes |
|---|---|---|
| 200 | ProjectList | |
| 401 | ErrorBody |
GET /v1/projects/{project_id}
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | ProjectDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
PATCH /v1/projects/{project_id}
Rename (projects:write).
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
Request body (application/json): RenameRequest
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | ProjectDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
DELETE /v1/projects/{project_id}
Soft-delete and revoke every key (projects:write).
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
GET /v1/projects/{project_id}/catalog/codegen
The tracking plan for atrix codegen (Bearer token with catalog:read).
Auth: Bearer token.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | CatalogCodegenExport | |
| 401 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/environments
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | EnvironmentList | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/erasure-requests
Auth: Bearer token with persons.erase.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | — | {requests: [ErasureJob]}, newest first (erasure-job.schema.json) |
| 403 | ErrorBody | missing persons.erase |
| 404 | ErrorBody |
POST /v1/projects/{project_id}/erasure-requests
Auth: Bearer token with persons.erase.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
Request body (application/json): ErasureCreate
| Field | Type | Required | Description |
|---|---|---|---|
distinct_ids | string[] | ||
person_id | string (uuid) | null | ||
reason | string | null |
| Status | Body | Notes |
|---|---|---|
| 202 | — | ErasureJob, pending (erasure-job.schema.json); raw ids go only to the region |
| 400 | ErrorBody | |
| 403 | ErrorBody | missing persons.erase |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/erasure-requests/{request_id}
Auth: Bearer token with persons.erase.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
request_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | — | ErasureJob with live per-store progress (erasure-job.schema.json) |
| 403 | ErrorBody | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/erasure-requests/{request_id}/certificate
Auth: Bearer token with persons.erase.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
request_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | — | {certificate, signature, verify}: the Ed25519-signed erasure certificate |
| 403 | ErrorBody | |
| 404 | ErrorBody | not completed yet, or unknown |
GET /v1/projects/{project_id}/experiments
Auth: Bearer token with experiments:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentListResponse | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
POST /v1/projects/{project_id}/experiments
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
Request body (application/json): ExperimentCreateRequest
| Field | Type | Required | Description |
|---|---|---|---|
alpha | number (double) | null | ||
attribution_window_hours | integer (int32) | null | ||
control_variant | string | null | ||
cuped | any | null | ExperimentCuped | ||
environment | string | null | ||
flag_id | string (uuid) | yes | |
guardrails | ExperimentGuardrail[] | null | ||
hypothesis | string | null | ||
key | string | yes | |
mde | number (double) | null | ||
method | string | null | ||
name | string | yes | |
power | number (double) | null | ||
primary_metric_id | string (uuid) | null | ||
secondary_metric_ids | string (uuid)[] | null | ||
winsor_pct | number (double) | null |
GET /v1/projects/{project_id}/experiments/{experiment_id}
Auth: Bearer token with experiments:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
PATCH /v1/projects/{project_id}/experiments/{experiment_id}
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
dry_run | query | boolean |
Request body (application/json): ExperimentUpdateRequest
| Field | Type | Required | Description |
|---|---|---|---|
alpha | number (double) | null | ||
attribution_window_hours | integer (int32) | null | ||
control_variant | string | null | ||
cuped | any | null | ExperimentCuped | ||
guardrails | ExperimentGuardrail[] | null | ||
hypothesis | string | null | ||
mde | number (double) | null | ||
method | string | null | ||
name | string | null | ||
power | number (double) | null | ||
primary_metric_id | string (uuid) | null | ||
secondary_metric_ids | string (uuid)[] | null | ||
winsor_pct | number (double) | null |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 409 | ErrorBody |
DELETE /v1/projects/{project_id}/experiments/{experiment_id}
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
dry_run | query | boolean |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | archived |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 409 | ErrorBody |
POST /v1/projects/{project_id}/experiments/{experiment_id}/launch
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
dry_run | query | boolean |
Request body (application/json): ExperimentTransitionRequest
| Field | Type | Required | Description |
|---|---|---|---|
override_block | boolean | null | ||
reason | string | null | ||
variant | string | null |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | flags.production needed in production |
| 404 | ErrorBody | |
| 409 | ErrorBody |
GET /v1/projects/{project_id}/experiments/{experiment_id}/results
Auth: Bearer token with experiments:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
refresh | path | boolean | null | yes | Recompute now instead of returning a result younger than 5 minutes. |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentResultsDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 409 | ErrorBody | |
| 503 | ErrorBody |
POST /v1/projects/{project_id}/experiments/{experiment_id}/ship
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
dry_run | query | boolean |
Request body (application/json): ExperimentTransitionRequest
| Field | Type | Required | Description |
|---|---|---|---|
override_block | boolean | null | ||
reason | string | null | ||
variant | string | null |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | experiments.ship (and flags.production in production) |
| 404 | ErrorBody | |
| 409 | ErrorBody | experiment_blocked |
POST /v1/projects/{project_id}/experiments/{experiment_id}/stop
Auth: Bearer token with experiments:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
experiment_id | path | string (uuid) | yes | |
dry_run | query | boolean |
Request body (application/json): ExperimentTransitionRequest
| Field | Type | Required | Description |
|---|---|---|---|
override_block | boolean | null | ||
reason | string | null | ||
variant | string | null |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 409 | ErrorBody |
POST /v1/projects/{project_id}/experiments/plan
Auth: Bearer token with experiments:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
Request body (application/json): ExperimentPlanRequest
| Field | Type | Required | Description |
|---|---|---|---|
alpha | number (double) | null | ||
control_units | number (double) | null | ||
daily_units | number (double) | null | ||
mde | number (double) | yes | |
mde_kind | string | null | ||
method | string | null | ||
metric | object | yes | |
power | number (double) | null | ||
variants | integer (int32) | null | (min 0) |
| Status | Body | Notes |
|---|---|---|
| 200 | ExperimentPlanResponse | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/flags
Auth: Bearer token with flags:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
archived | path | boolean | null | yes | Include archived flags. |
search | path | string | null | yes | Case-insensitive match on key or name. |
| Status | Body | Notes |
|---|---|---|
| 200 | FlagListResponse | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
POST /v1/projects/{project_id}/flags
Auth: Bearer token with flags:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
Request body (application/json): FlagCreateRequest
| Field | Type | Required | Description |
|---|---|---|---|
description | string | null | ||
key | string | yes | |
kind | string | null | boolean | |
name | string | yes | |
payload | object | null | ||
rules | object[] | null | ||
stickiness | string | null | ||
tags | string[] | null | ||
variants | object[] | null |
GET /v1/projects/{project_id}/flags/{flag_id}
Auth: Bearer token with flags:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
flag_id | path | string (uuid) | yes |
PATCH /v1/projects/{project_id}/flags/{flag_id}
Auth: Bearer token with flags:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
flag_id | path | string (uuid) | yes | |
dry_run | query | boolean |
Request body (application/json): FlagUpdateRequest
| Field | Type | Required | Description |
|---|---|---|---|
description | string | null | ||
name | string | null | ||
owner_id | string (uuid) | null | ||
tags | string[] | null |
DELETE /v1/projects/{project_id}/flags/{flag_id}
Auth: Bearer token with flags:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
flag_id | path | string (uuid) | yes | |
dry_run | query | boolean |
PATCH /v1/projects/{project_id}/flags/{flag_id}/environments/{environment}
Auth: Bearer token with flags:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
flag_id | path | string (uuid) | yes | |
environment | path | string | yes | |
dry_run | query | boolean |
Request body (application/json): FlagEnvironmentUpdateRequest
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | null | ||
payload | object | null | null clears the payload. | |
rules | object[] | null | ||
salt | string | null | ||
stickiness | string | null | ||
variants | object[] | null |
| Status | Body | Notes |
|---|---|---|
| 200 | FlagDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | missing flags:write, or flags.production for a live production config |
| 404 | ErrorBody | |
| 409 | ErrorBody |
GET /v1/projects/{project_id}/flags/publications
Auth: Bearer token with flags:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
environment | path | string | null | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | FlagPublicationListResponse | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/integrations
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | IntegrationList | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
POST /v1/projects/{project_id}/integrations
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
Idempotency-Key | header | string | null |
Request body (application/json): CreateIntegrationRequest
| Field | Type | Required | Description |
|---|---|---|---|
config | object | null | ||
name | string | null | ||
provider | string | yes | stripe |
secret | string | null | Stripe: the endpoint's signing secret (whsec_…). RevenueCat: the Authorization header value configured in its dashboard. App Store and Google Play take none. Optional at creation: without it the integration is pending_secret (deliveries refused) until an update sets it. |
| Status | Body | Notes |
|---|---|---|
| 201 | IntegrationDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody | |
| 503 | ErrorBody |
GET /v1/projects/{project_id}/integrations/{integration_id}
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
integration_id | path | string (uuid) | yes |
| Status | Body | Notes |
|---|---|---|
| 200 | IntegrationDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
PATCH /v1/projects/{project_id}/integrations/{integration_id}
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
integration_id | path | string (uuid) | yes | |
Idempotency-Key | header | string | null |
Request body (application/json): UpdateIntegrationRequest
| Field | Type | Required | Description |
|---|---|---|---|
config | object | null | ||
name | string | null | ||
secret | string | null | Replace the stored secret (rotation). | |
status | string | null | active |
| Status | Body | Notes |
|---|---|---|
| 200 | IntegrationDto | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
DELETE /v1/projects/{project_id}/integrations/{integration_id}
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
integration_id | path | string (uuid) | yes |
POST /v1/projects/{project_id}/integrations/{integration_id}/rotate-token
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
integration_id | path | string (uuid) | yes | |
Idempotency-Key | header | string | null |
| Status | Body | Notes |
|---|---|---|
| 200 | IntegrationDto | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
GET /v1/projects/{project_id}/keys
Auth: Bearer token with projects:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
POST /v1/projects/{project_id}/keys/{key_id}/revoke
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
key_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
POST /v1/projects/{project_id}/keys/{key_id}/rotate
Auth: Bearer token with projects:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes | |
key_id | path | string (uuid) | yes | |
dry_run | query | boolean | ||
Idempotency-Key | header | string | null |
Request body (application/json): RotateKeyRequest
| Field | Type | Required | Description |
|---|---|---|---|
keep_old | boolean | Keep the old key working (revoke it later). Default: revoke it now. |
| Status | Body | Notes |
|---|---|---|
| 200 | RotateKeyResponse | |
| 404 | ErrorBody | |
| 409 | ErrorBody |
POST /v1/projects/{project_id}/query
Validate a Query IR and get the region request to run it (query:read). The control plane returns a query:read region token and the region endpoint; results never pass through it.
Auth: Bearer token with query:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
Request body (application/json): V1QueryRequest
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | null | production | |
include_sql | boolean | Ask the region to include the compiled SQL in its answer. | |
query | object | yes | A Query IR v1 document (packages/contracts/schemas/query-ir.schema.json). |
refresh | boolean | Bypass the region's result cache. |
| Status | Body | Notes |
|---|---|---|
| 200 | V1QueryResponse | |
| 400 | ErrorBody | |
| 403 | ErrorBody | |
| 404 | ErrorBody |
POST /v1/projects/{project_id}/region-token
Region token carrying the token's regional scopes (∩ the owner's role), optionally narrowed.
Auth: Bearer token.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string (uuid) | yes |
Request body (application/json): RegionTokenRequest
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | null | production | |
scopes | string[] | null | Narrow further. Omit for every regional scope you hold. |
| Status | Body | Notes |
|---|---|---|
| 200 | RegionTokenResponse | |
| 403 | ErrorBody | |
| 404 | ErrorBody |