Apps API · Organizations
Organizations: 5 endpoints
GET /api/v1/organizations
List my organizations
Scope: org:organization:read · Called with: appToken · operationId: list-my-organizations
Required app scope: org:organization:read.
Returns organizations the authenticated identity is a member of. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | integer (int32) | Page number (default: 1) | |
page_size |
query | integer (int32) | Items per page (default: 20, max: 100) | |
order_by |
query | string | Sort expression, e.g. created_at:desc |
Responses
200OK —application/json·PageListResponseOrganizationSummaryBodydefaultError —application/problem+json·D8Error
GET /api/v1/organizations/{org_id}
Get organization details
Scope: org:organization:read · Called with: appToken · operationId: get-organization
Required app scope: org:organization:read.
Returns detailed information about a specific organization. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | Organization UUID |
Responses
200OK —application/json·DataResponseOrganizationDetailBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/organizations/{org_id}
Update organization info
Scope: org:organization:write · Called with: appToken · operationId: update-organization
Required app scope: org:organization:write.
Updates the organization's name, slug, or industry (industry / industry_other). Name / slug require the org.manage permission; industry / industry_other require org.industry (org-owner only for now). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | Organization UUID |
Request body
application/json · UpdateOrganizationRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
industry |
string: retail_ecom, b2b_trade, content_media, consumer_brand, logistics, manufacturing, other |
Update the organization industry key. Switching to a value other than 'other' clears industry_other. Existing agents are not renamed. | |
industry_other |
string | Update the free-text supplement; only valid when the resulting industry is 'other'. Blank clears it; omitted keeps the stored text while the industry stays 'other'. | |
name |
string | Update organization name | |
slug |
string | Update organization slug (globally unique) |
Responses
200OK —application/json·DataResponseUpdateOrganizationDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/organizations/{org_id}/deletion-precheck
Read-only organization deletion precheck
Scope: org:organization:read · Called with: appToken · operationId: get-organization-deletion-precheck
Required app scope: org:organization:read.
Returns what deleting this Organization would affect — Agent count, conversation count, current subscription and credit balance — plus the per-participant impact breakdown and anything that currently blocks deletion. Strictly read-only: it creates no deletion Job, does not delete the Organization, does not deactivate the billing account and writes no participant deletion fence. Only the current org-owner may call it. Numbers that are unavailable are null; clients must render "unknown" rather than 0. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | Organization UUID |
Responses
200OK —application/json·DataResponseOrganizationDeletionPrecheckDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/organizations/{org_id}/storage-quota
Get organization storage quota
Scope: org:organization:read · Called with: appToken · operationId: get-organization-storage-quota
Required app scope: org:organization:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Responses
200OK —application/json·DataResponseQuotaBodydefaultError —application/problem+json·D8Error
