For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Organizations (Beta)

List and manage organizations the authenticated caller can access.

List organizations the caller can access

Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid org_id values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org.

{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMembership"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"List organizations the caller can access","description":"Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid `org_id` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org."}}},"components":{"schemas":{"OrganizationMembership":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID. Pass as `org_id` to other tools."},"name":{"type":"string","description":"Human-readable organization name."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'), or null if unset. For other org-management fields (postal address, deactivation flag, created_at), use `get_organization` on a specific `org_id`.","nullable":true},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"Caller's role in this org: 'user', 'admin', 'support', 'cloud_rep', or 'restricted_user'. Staff users are reported as 'admin' for every active org."},"kind":{"description":"How the caller has access: 'direct' (regular member), 'staff' (staff-level access to every active org), or 'partnership' (inherited via a channel partnership).","enum":["direct","staff","partnership"]},"is_primary":{"type":"boolean","description":"True for the org the caller's tokens default to when no `org_id` is passed. Matches the earliest-joined direct membership returned by `User.active_memberships`."},"denied_permissions":{"type":"array","description":"List of `Resource:action` strings the caller's role is denied (e.g. 'PurchasePlanV2:execute'). Anything not listed is permitted. Use to gate write/destructive recommendations.","items":{"type":"string"}}},"required":["denied_permissions","id","is_primary","kind","name","role"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}

Get an organization's management details

Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at. For the cross-org list of orgs the caller can access (with role / kind / denied_permissions), use GET /organizations.

{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Get an organization's management details","description":"Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at. For the cross-org list of orgs the caller can access (with role / kind / denied_permissions), use `GET /organizations`."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateOrganization":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New organization name."},"domain":{"type":"string","minLength":1,"description":"New email domain, or null to clear.","nullable":true},"primary_address":{"description":"Replacement primary address. Send the full address object. Pass null to clear the existing address.","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"additionalProperties":false}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}

Update an organization's management details

Partial-update: every field is optional. Send only the fields you want to change. Sending primary_address replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use POST /organizations/<org_id>/deactivate. Requires the caller to have admin role on the org (the Organization:write casbin permission).

{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganization"}}}},"tags":["Organizations (Beta)"],"summary":"Update an organization's management details","description":"Partial-update: every field is optional. Send only the fields you want to change. Sending `primary_address` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use `POST /organizations/<org_id>/deactivate`. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateOrganization":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New organization name."},"domain":{"type":"string","minLength":1,"description":"New email domain, or null to clear.","nullable":true},"primary_address":{"description":"Replacement primary address. Send the full address object. Pass null to clear the existing address.","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"additionalProperties":false}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}

Deactivate an organization

Soft-disables the organization: it stops appearing in list_organizations results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the Organization:write casbin permission).

{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}/deactivate":{"post":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Deactivate an organization","description":"Soft-disables the organization: it stops appearing in `list_organizations` results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}