Orgs endpoints
POST /api/v1/invites/accept
Section titled “POST /api/v1/invites/accept”Accept Invite
Request body (application/json, required): InviteAcceptIn
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: MembershipOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/invites/preview
Section titled “GET /api/v1/invites/preview”Preview Invite
Show the org and role an invite grants, without accepting it.
Requires a signed-in user (the invitee), like accepting does. Unknown, used and expired tokens all get the same 404, so the endpoint does not reveal which invites exist.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
token |
query | string | yes | min length 1, max length 128 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: InvitePreviewOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs
Section titled “POST /api/v1/orgs”Create Org
Request body (application/json, required): OrgCreateIn
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: OrgOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/orgs/{org_id}
Section titled “DELETE /api/v1/orgs/{org_id}”Delete Org
Delete the organization with its projects, traces, keys, members, invites and audit log.
Only an owner may, and only by typing the organization’s slug as confirm. Everything goes
in one transaction: it is all deleted or none of it is. This is synchronous, which is fine for
the size of organization this runs; a very large one needs a background job.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Request body (application/json, required): OrgDeleteIn
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}
Section titled “GET /api/v1/orgs/{org_id}”Get Org
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: OrgWithRoleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/orgs/{org_id}
Section titled “PATCH /api/v1/orgs/{org_id}”Update Org
Rename the organization, or require (or stop requiring) two-factor authentication.
name needs org:update (admins and owners) and require_2fa needs org:security (owners);
a request with both needs both, and is refused whole. Only values that change are applied and
audited, in one org.update event, so repeating a request is a no-op.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Request body (application/json, required): OrgUpdateIn
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: OrgOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/audit
Section titled “GET /api/v1/orgs/{org_id}/audit”List Audit Events
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no | |
action |
query | string or null | no | min length 1, max length 100 |
actor_id |
query | string (uuid) or null | no | |
from |
query | string (date-time) or null | no | |
to |
query | string (date-time) or null | no | |
project_id |
query | string (uuid) or null | no | |
outcome |
query | "success" | "failure" or null |
no | |
actor_type |
query | "user" | "token" | "system" | "cli" or null |
no |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_AuditEventOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/audit/export.csv
Section titled “GET /api/v1/orgs/{org_id}/audit/export.csv”Download the audit log as CSV
The audit log, filtered like GET /orgs/{org_id}/audit, streamed as CSV (newest first).
A log with more than 50 000 matching events is refused before anything is sent.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
action |
query | string or null | no | min length 1, max length 100 |
actor_id |
query | string (uuid) or null | no | |
from |
query | string (date-time) or null | no | |
to |
query | string (date-time) or null | no | |
project_id |
query | string (uuid) or null | no | |
outcome |
query | "success" | "failure" or null |
no | |
actor_type |
query | "user" | "token" | "system" | "cli" or null |
no |
| Status | Description | Body |
|---|---|---|
| 200 | The audit log as CSV. | text/csv: any |
| 422 | More than 50 000 events match (EXPORT_TOO_LARGE). |
none |
GET /api/v1/orgs/{org_id}/audit/export.jsonl
Section titled “GET /api/v1/orgs/{org_id}/audit/export.jsonl”Download the audit log as JSON Lines
The audit log, filtered like GET /orgs/{org_id}/audit, one event object per line
(newest first), for log tools. A log with more than 50 000 matching events is refused.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
action |
query | string or null | no | min length 1, max length 100 |
actor_id |
query | string (uuid) or null | no | |
from |
query | string (date-time) or null | no | |
to |
query | string (date-time) or null | no | |
project_id |
query | string (uuid) or null | no | |
outcome |
query | "success" | "failure" or null |
no | |
actor_type |
query | "user" | "token" | "system" | "cli" or null |
no |
| Status | Description | Body |
|---|---|---|
| 200 | The audit log as JSON Lines: one AuditEventOut per line. |
application/x-ndjson: any |
| 422 | More than 50 000 events match (EXPORT_TOO_LARGE). |
none |
GET /api/v1/orgs/{org_id}/audit/integrity
Section titled “GET /api/v1/orgs/{org_id}/audit/integrity”Audit Integrity
Recompute the org’s audit hash chain from the stored events and say where it breaks.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AuditIntegrityOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/orgs/{org_id}/audit/stream
Section titled “DELETE /api/v1/orgs/{org_id}/audit/stream”Delete Audit Stream
Stop streaming and forget the endpoint and its secret.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/audit/stream
Section titled “GET /api/v1/orgs/{org_id}/audit/stream”Get Audit Stream
The org’s audit stream, or null when none is set up. Never the signing secret.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AuditStreamOut or null |
| 422 | Validation Error | application/json: HTTPValidationError |
PUT /api/v1/orgs/{org_id}/audit/stream
Section titled “PUT /api/v1/orgs/{org_id}/audit/stream”Put Audit Stream
Create the stream (its secret is returned this once) or change its URL or switch.
A new stream sends the events written after it is created. 422 VALIDATION_ERROR for a URL
the webhook rules refuse (422 UNSAFE_URL), 409 NOT_CONFIGURED without CREDENTIALS_KEYS.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Request body (application/json, required): AuditStreamIn
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AuditStreamSavedOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/audit/stream/rotate-secret
Section titled “POST /api/v1/orgs/{org_id}/audit/stream/rotate-secret”Rotate Audit Stream Secret
Replace the signing secret; the new one is returned this once. The old one stops at once.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AuditStreamSavedOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/audit/stream/test
Section titled “POST /api/v1/orgs/{org_id}/audit/stream/test”Test Audit Stream
POST one signed audit.test event to the endpoint now and report how it answered.
At most 10 an hour per organization (429), like a channel’s test.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AuditStreamTestOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/invites
Section titled “GET /api/v1/orgs/{org_id}/invites”List Invites
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of InviteOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/invites
Section titled “POST /api/v1/orgs/{org_id}/invites”Create Invite
Create an invite and return its link; with an email and a sender, also mail it.
The invite, its audit event and the queued email commit in one transaction. Mailing only changes how the link reaches someone: the invite is still accepted by any signed-in holder of the link, whatever address it was mailed to.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Request body (application/json, required): InviteCreateIn
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: InviteCreatedOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/orgs/{org_id}/invites/{invite_id}
Section titled “DELETE /api/v1/orgs/{org_id}/invites/{invite_id}”Revoke Invite
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
invite_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/members
Section titled “GET /api/v1/orgs/{org_id}/members”List Members
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of MemberOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/orgs/{org_id}/members/{user_id}
Section titled “DELETE /api/v1/orgs/{org_id}/members/{user_id}”Remove Member
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
user_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/orgs/{org_id}/members/{user_id}
Section titled “PATCH /api/v1/orgs/{org_id}/members/{user_id}”Update Member
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
user_id |
path | string (uuid) | yes |
Request body (application/json, required): MemberUpdateIn
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: MemberOut |
| 422 | Validation Error | application/json: HTTPValidationError |