{ "openapi": "3.1.0", "info": { "title": "AstralBeam API", "version": "1.0.0", "description": "# Getting started\n\nCreate customer accounts (Tenants) and their users (TenantUsers) over HTTPS from any backend language. These records are separate from dashboard members.\n\nUse the HTTP examples below or download the [OpenAPI document](/api/openapi.json). For embedded chat, see the separate [SDK guides](/docs/sdk).\n\n## Prerequisites\n\nIn the dashboard, select your organization and open **API keys** as an owner or developer. Create a key and copy the full `key_…_abo_…` value into your server's `ASTRALBEAM_API_KEY` secret. Never send it to the browser.\n\nThe hosted API base is `https://astralbeam.ai/api`. Self-hosted installations use their own origin with the `/api` base, for example `https://beam.example.com/api`.\n\nRun the example once with your own stable identities. Creating them again returns `409`. Each request is independent, not one transaction.\n\n## Create a Tenant and its users\n\nWith `ASTRALBEAM_API_KEY` already set securely, create a Tenant:\n\n```sh\nexport ASTRALBEAM_API_URL=\"https://astralbeam.ai/api\"\ncurl --include \"$ASTRALBEAM_API_URL/v1/tenants\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data '{\"external_id\":\"customer-42\",\"name\":\"Acme Logistics\",\"metadata\":{\"plan\":\"pro\",\"region\":\"eu-west-1\"}}'\n```\n\nExpect `201 Created`, a JSON record, and a `Location` header. Copy the returned internal `id` for [TenantUser requests](/docs/api#tag/tenant_users).\n\nCopy that returned `id` into `TENANT_ID`, then create a user belonging to the Tenant:\n\n```sh\nTENANT_ID=\"\"\ncurl --include \"$ASTRALBEAM_API_URL/v1/tenants/$TENANT_ID/tenant_users\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data '{\"external_id\":\"user-7\",\"name\":\"Alex Morgan\"}'\n```\n\nExpect `201 Created` with the new user's internal `id`. Keep `user-7` as their external identity in your application and chat tokens.\n\nList that Tenant's users:\n\n```sh\ncurl --get \"$ASTRALBEAM_API_URL/v1/tenants/$TENANT_ID/tenant_users\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\" \\\n --data-urlencode \"page_size=20\"\n```\n\nExpect `200 OK` with an `items` array. Follow the returned cursor to load more users. See [Pagination](/docs/api#description/pagination).\n\n## Identities and write behavior\n\nOn creation, omitted `name` defaults to `null`, `metadata` to `{}`, and TenantUser `admin` to `false`. On PATCH, omitted fields stay unchanged. Metadata updates replace the whole object, not individual keys. `{}` clears it and `null` is rejected. `name: null` clears a name. Stored `admin` is data, not permission to issue privileged JWTs.\n\n| Your identity | API field | Chat token field |\n| --- | --- | --- |\n| Customer ID | Tenant `external_id` | `tenant.id` |\n| Tenant-local user ID | TenantUser `external_id` | `user.id` |\n| Returned internal ID | Response `id`, used in resource paths | Do not use as your external identity |\n\nMinting a chat token does not provision these records. API calls do not mint tokens. For embedded chat, follow the separate [token endpoint guide](/docs/sdk/authentication).\n\n## Recover from an uncertain create\n\nIf a create times out or returns `409`, list with `filter[external_id]` set to the exact external ID before deciding what to do next. Inspect `items[0]`: a found record proves that identity exists, not that every attempted field matches. An empty page does not prove a timed-out request cannot still commit. These APIs do not offer idempotency keys.\n\nThe [Tenants](/docs/api#tag/tenants) and [TenantUsers](/docs/api#tag/tenant_users) references include filtering examples. For permissions and complete schemas, see [authentication](/docs/api#description/authentication) and the [OpenAPI contract](/api/openapi.json).\n\n\n# Authentication\n\nAuthenticate management requests with an organization API key on your server, or a scoped JWT in a browser. Chat requires a tenant JWT. See the [API quickstart](/docs/api#description/getting-started) and [OpenAPI contract](/api/openapi.json).\n\n## Organization API keys\n\nSend the full `key_…_abo_…` value through `X-API-Key` or `Authorization: Bearer `. If both are present, `X-API-Key` takes precedence. Keys manage resources throughout their organization and retain their configured rate limits. Dashboard session cookies alone are not accepted. Never expose an organization key to browser code.\n\n## Examples\n\nSet `ASTRALBEAM_API_KEY` securely in your server environment, then send it with each request:\n\n```sh\ncurl \"https://astralbeam.ai/api/v1/tenants\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\"\n```\n\nAlternatively, with an admin JWT in `ASTRALBEAM_TOKEN`, use Bearer authentication.\n\n```sh\ncurl \"https://astralbeam.ai/api/v1/tenants\" \\\n -H \"Authorization: Bearer $ASTRALBEAM_TOKEN\"\n```\n\nBoth return `200 OK` with a paginated list in the credential's scope. POST/PATCH requests also require `Content-Type: application/json`.\n\n## Tenant administrator JWTs\n\nA valid chat JWT with signed `user.admin: true` can read its own Tenant and read/create/update TenantUsers within it. Tenant writes are forbidden. Non-admin JWTs cannot access these resource operations.\n\nThe JWT carries separate `user` and `tenant` claims. Signed `tenant.id` is an external identity, resolved within the issuing organization. Authentication never upserts identities or requires a persisted calling TenantUser.\n\nCall `GET /api/v1/tenants` with the JWT to obtain your Tenant's internal `id` for TenantUser routes. It returns an empty list if the Tenant does not exist. TenantUser lists and other reads/writes return `404` for a missing or inaccessible Tenant or record.\n\n**Stored TenantUser admin does not grant or revoke JWT privileges.** Authority comes from the signed claim until expiry or backing-key invalidation.\n\nJWT resource requests have a separate limit of 100 requests per five minutes per organization, external Tenant, and external user identity. Throttling returns `429` and `Retry-After` seconds.\n\n## Chat and downloads\n\nChat accepts tenant JWTs without administrator privileges, but not API keys or organization-management JWTs. Configuration reads do not synchronize identity. Before sending, call `POST /api/v1/me` and select a participant-authorized saved conversation. The SDK handles both. Endpoint operations select three independent rate buckets per Organization, Tenant, and tenant user: 20 new turns, 200 tool-result submissions, and 200 uploads per minute.\n\nDownloads pass the saved `fileId` and `threadId`. Tenant JWTs require current conversation participation. Administrative downloads also pass `tenantId` and accept an Organization API key, an organization-management JWT with current directory-read permission, or a signed Tenant admin JWT within its Tenant. Published files survive sandbox shutdown.\n\n## Current user\n\nSend a tenant or organization JWT to `POST /api/v1/me` without a request body. Identity comes only from the verified JWT, and query parameters are rejected. API keys and dashboard cookies cannot authenticate this endpoint.\n\nTenant JWTs return `{ scope: \"tenant\", organization: { id }, tenant, user }`, using the public Tenant and TenantUser records. The request upserts only the signed Tenant and current TenantUser in one transaction. Ordinary non-admin users can synchronize themselves. Omitted names, metadata, and admin preserve existing values. Supplied metadata replaces the stored object, and explicit `user.admin` updates stored admin. New records default to null names, empty metadata, and false admin.\n\nOrganization JWTs return `{ scope: \"organization\", organization: { id }, user: { id, name, email, role } }`. Membership and role are read again, including for viewers, without creating users, memberships, tenants, or sessions. Removed membership returns `403`.\n\nSuccess is `200` with `Cache-Control: no-store`. Invalid or revoked JWTs return `401`. Synchronization has its own 100-request-per-five-minute bucket per authenticated identity. Throttling returns `429` with `Retry-After`.\n\n## Organization management JWTs\n\nUse these tokens for an existing organization member's Tenant and TenantUser operations. Each request checks current membership and roles: owners and developers can read and write, viewers can only read. Recognized roles combine their grants. Missing membership or permission returns `403`. Role changes apply immediately.\n\nThe issuer must authenticate the operator and authorize access to the selected organization. The issuing API key retains organization-wide authority. Use the [SDK helper](/docs/sdk/api#browser-organization-jwt), or sign these fields with HS256:\n\n| Field | Value |\n| --- | --- |\n| Protected `typ` | `astralbeam-organization+jwt` |\n| `ver` | `1` |\n| `email` | Verified operator email, matched case-insensitively to an existing member |\n| `organization_id`, `iss` | Organization UUID matching the signing API key |\n| `aud` | `astralbeam` |\n| `iat`, `exp` | Epoch seconds, 60–600 seconds apart |\n\nUse the API key's ID as protected `kid` and its hashed secret as the signing key, as described in the [token format](/docs/sdk/authentication#mint-tokens-without-javascript). The key must remain enabled and unexpired. Do not include `role`, `roles`, `admin`, `sub`, or user-ID claims.\n\nThese tokens cannot authenticate chat, create dashboard sessions, or manage dashboard configuration. They create no users or memberships. Requests are limited to 100 per five minutes per organization and resolved member. Changing the token or email does not reset the bucket.\n\n## Browser transport\n\nThe API permits credential-free CORS for GET, POST, PUT, PATCH, DELETE, and OPTIONS. Browser callers must use scoped JWTs, not organization keys. Preflight needs no authentication. Responses use `Cache-Control: no-store` except successful chat images and previews, which may use a private browser cache for 60 seconds and vary by authorization and preview headers.\n\n\n# Pagination\n\nAll lists support cursor-based pagination in both directions. Use the returned cursors to fetch the next or previous page.\n\n## Requests and responses\n\n- `page_size`: positive integer, default 20. Values above 100 are accepted and capped.\n- `page_after`: a returned `page_after` value, to fetch the next page.\n- `page_before`: a returned `page_before` value, to fetch the previous page.\n- At most one direction is accepted. Unknown/duplicate parameters, invalid sizes, and invalid or wrong-scope cursors return `400`.\n\nResponses contain `items`, `page_after`, and `page_before`. Pass a non-null cursor unchanged as the same-named parameter to continue. A null cursor means no page remains in that direction. Response cursors are continuations, not echoes of the request.\n\nExample response for `page_size=1`. The cursor is a placeholder. Use the actual returned value in requests:\n\n```json\n{\n \"items\": [\n {\n \"id\": \"019eed68-fd00-7c42-9a61-53b3a890d276\",\n \"external_id\": \"customer-42\",\n \"name\": \"Acme Logistics\",\n \"metadata\": { \"plan\": \"pro\", \"region\": \"eu-west-1\" },\n \"created_at\": \"2026-06-22T09:30:00.000Z\",\n \"updated_at\": \"2026-06-22T09:30:00.000Z\"\n }\n ],\n \"page_after\": \"\",\n \"page_before\": null\n}\n```\n\nStop when your direction's cursor is null, not when a page looks short. Empty pages have no items and both cursors null. You can also follow the `Link` header's `next` or `prev` relation. Page size may change between requests.\n\nTenants and TenantUsers within a Tenant are ordered by internal `id`, ascending. Backward traversal preserves display order.\n\n## Live listings\n\nListings are live. Inserts behind a cursor may be missed, and deleted rows disappear. A continuation can return an empty page. Treat cursors as opaque and reuse them only for the same collection and authorized scope. If rejected, restart without a cursor.\n\nTenantUser lists bind cursors to the requested Tenant as well as the caller's scope. Both collections also bind cursors to the active filters. Adding, removing, or changing a filter while reusing a cursor returns `400`. Start without a cursor when changing filters. Pagination links preserve the filters.\n\n## Filters\n\nBoth list endpoints accept optional `filter[external_id]`, an exact, case-sensitive, untrimmed string of 1–255 characters. It returns zero or one item in the normal pagination envelope. No match is `200` with an empty page. Missing or inaccessible parent Tenants still return `404` on nested TenantUser lists.\n\nBrackets belong to the parameter name. The value is plain text, not a JSON filter object.\n\nBoth lists also accept `q`, up to 255 characters, for case-insensitive substring matching against name or external ID. Leading/trailing whitespace is trimmed, and empty search means no search filter. Percent signs, underscores, and backslashes are literal characters, not wildcards. NUL characters are rejected with `400`.\n\nTenantUser lists additionally accept `filter[admin]=true` or `filter[admin]=false` to filter stored status. Search, exact external-ID, and admin filters combine with AND. Stored admin does not change JWT authority.\n\nEmpty exact/admin filter values, repeated parameters, unsupported filters, and the unnamespaced `external_id` parameter return `400`. Sorting, full-text search, inclusion, selection, and counts are not supported.\n\n## Examples\n\nWith `ASTRALBEAM_API_KEY` set securely in your server environment, request the first page. `--include` shows the status and response headers alongside the JSON body.\n\nFor exact filtering, add `--data-urlencode \"filter[external_id]=customer-42\"` and keep that parameter on any continuation request.\n\n```sh\nexport ASTRALBEAM_API_URL=\"https://astralbeam.ai/api\"\ncurl --include --get \"$ASTRALBEAM_API_URL/v1/tenants\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\" \\\n --data-urlencode \"page_size=1\"\n```\n\nIf the returned `page_after` is not null, copy it into `PAGE_AFTER`:\n\n```sh\nPAGE_AFTER=\"\"\ncurl --include --get \"$ASTRALBEAM_API_URL/v1/tenants\" \\\n -H \"X-API-Key: $ASTRALBEAM_API_KEY\" \\\n --data-urlencode \"page_size=1\" \\\n --data-urlencode \"page_after=$PAGE_AFTER\"\n```\n\nTo traverse backward, send the returned `page_before` as the `page_before` request parameter instead, and stop when it is null. Never send both directions together.\n\nThe example response above also includes a `Link` header with the returned `page_after` and `rel=\"next\"`. Resolve relative links against the request URL.\n\n# Errors\n\nErrors follow the `AstralBeamApiError` schema and use RFC 9457 `application/problem+json`: `type`, `title`, `status`, `detail`, and optional validation `issues` with `path` and `message`. A `500` also carries a `reference` that matches the server's log entry for the failure, so quote it when you report the problem.\n\nEndpoint descriptions specify exceptions to these shared error conventions:\n\n| Status | Meaning |\n| --------- | ------------------------------------------------------------ |\n| 400 | Invalid path/query/cursor or malformed chat input |\n| 401 / 403 | Invalid credentials / insufficient authority |\n| 404 | Missing or out-of-scope record |\n| 409 | Duplicate identity, stale revision, or conflicting operation |\n| 413 | Chat request exceeds 32 MiB |\n| 415 | Unsupported media type or encoding |\n| 422 | Malformed JSON, invalid write fields or empty PATCH |\n| 429 | Rate or usage limit reached, observe Retry-After |\n| 500 / 503 | Safe internal error / setup unavailable |\n\nA chat request refused by a usage limit adds a `usage_limit` member with the limit's display `name` and its `resets_at` time. See [Usage limits](/docs/dashboard/usage-limits).\n\nMissing and out-of-scope records both return `404`. Resource POST/PATCH requests reject unknown fields, and PATCH must supply at least one mutable field. Invalid resource writes return `422`. Chat preserves AG-UI camelCase input and reports malformed input as `400`. Failures after streaming starts are AG-UI `RUN_ERROR` events, not HTTP error responses.\n\nAn invalid `admin` value, for example, returns `422 Unprocessable Content` with `Content-Type: application/problem+json`:\n\n```json\n{\n \"type\": \"about:blank\",\n \"title\": \"Unprocessable Content\",\n \"status\": 422,\n \"detail\": \"Invalid request body.\",\n \"issues\": [{ \"path\": \"body.admin\", \"message\": \"Expected boolean\" }]\n}\n```\n\nA timed-out or aborted mutation may already have committed. Check its outcome before retrying. External proxies can return non-JSON errors, so inspect status and content type before parsing a failure body.\n\nA throttled response includes `Retry-After` in seconds. Wait that long before trying again.\n" }, "paths": { "/api/v1/docs/search": { "get": { "tags": [ "documentation" ], "operationId": "searchDocumentation", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "DocumentationSearch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentationSearch" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Search the published guides and API reference. Returns up to five matching pages with relative URLs and the best matching section. Accepts the same credentials as the resource APIs.", "summary": "Search documentation" } }, "/api/v1/tenants": { "get": { "tags": [ "tenants" ], "operationId": "listTenants", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000]*$", "description": "Case-insensitive literal substring of name or external_id. Trimmed, blank means no search." }, "required": false }, { "name": "filter[external_id]", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Exact, case-sensitive external ID; whitespace is preserved. Returns zero or one item." }, "required": false }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "Live keyset page. Pass either non-null continuation value as the same-named request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "List Tenants in internal ID order. q searches name or external ID as a case-insensitive literal substring. filter[external_id] adds an exact match. Organization keys and organization-management JWTs see their organization; admin tenant JWTs see only their signed Tenant. Keep filters unchanged when reusing cursors. Live listing, not a snapshot.", "summary": "List Tenants" }, "post": { "tags": [ "tenants" ], "operationId": "createTenant", "parameters": [], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "201": { "description": "TenantRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecordEncoded" } } }, "headers": { "location": { "schema": { "type": "string" }, "required": true } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Create a Tenant with an exact customer-provided external_id. Requires an organization API key or organization-management JWT with a current owner/developer role. An external_id already used in this organization returns 409; creation never upserts.", "summary": "Create a Tenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantInput" } } }, "required": true } } }, "/api/v1/tenants/{id}": { "get": { "tags": [ "tenants" ], "operationId": "getTenant", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "TenantRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecordEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Get a Tenant by internal UUID, not external_id.", "summary": "Get a Tenant" }, "patch": { "tags": [ "tenants" ], "operationId": "updateTenant", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "TenantRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecordEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Update supplied name/metadata fields only. Requires an organization API key or organization-management JWT with a current owner/developer role. name:null clears the name; metadata replaces the object. Last-write-wins; no upsert.", "summary": "Update a Tenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantInput" } } }, "required": true } } }, "/api/v1/tenants/{tenant_id}/tenant_users": { "get": { "tags": [ "tenant_users" ], "operationId": "listUsersForTenant", "parameters": [ { "name": "tenant_id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000]*$", "description": "Case-insensitive literal substring of name or external_id. Trimmed, blank means no search." }, "required": false }, { "name": "filter[external_id]", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Exact, case-sensitive external ID; whitespace is preserved. Returns zero or one item." }, "required": false }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "filter[admin]", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "Live keyset page in ascending ID order within one Tenant. Pass either non-null continuation value as the same-named request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "List users of one Tenant in internal ID order. q searches name or external ID as a case-insensitive literal substring. Exact filter[external_id] and filter[admin] combine with AND. No matching user returns an empty page; missing and out-of-scope Tenants return 404. Cursors cannot be reused for another Tenant or filter. Live listing, not a snapshot.", "summary": "List TenantUsers" }, "post": { "tags": [ "tenant_users" ], "operationId": "createTenantUser", "parameters": [ { "name": "tenant_id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "201": { "description": "TenantUserRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserRecordEncoded" } } }, "headers": { "location": { "schema": { "type": "string" }, "required": true } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Create a TenantUser under the internal tenant_id path identifier, with a customer-provided tenant-local external_id. An external_id already used in this Tenant returns 409; the same external_id in another Tenant is allowed. Stored admin does not change signed JWT authority.", "summary": "Create a TenantUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantUserInput" } } }, "required": true } } }, "/api/v1/tenants/{tenant_id}/tenant_users/{id}": { "get": { "tags": [ "tenant_users" ], "operationId": "getTenantUser", "parameters": [ { "name": "tenant_id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true }, { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed6a-d1c0-7543-b892-608cb6e174da" ] }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "TenantUserRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserRecordEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Get a TenantUser by the internal tenant_id and id pair within the authorized scope. No identity upsert.", "summary": "Get a TenantUser" }, "patch": { "tags": [ "tenant_users" ], "operationId": "updateTenantUser", "parameters": [ { "name": "tenant_id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true }, { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed6a-d1c0-7543-b892-608cb6e174da" ] }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "TenantUserRecord", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserRecordEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Update supplied name/metadata/admin fields only. Stored admin does not grant or revoke JWT authority. name:null clears the name; metadata replaces the object.", "summary": "Update a TenantUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantUserInput" } } }, "required": true } } }, "/api/v1/tenants/{tenant_id}/tenant_users/usage": { "get": { "tags": [ "tenant_users" ], "operationId": "getTenantUserUsage", "parameters": [ { "name": "tenant_id", "in": "path", "schema": { "type": "string", "format": "uuid", "examples": [ "019eed68-fd00-7c42-9a61-53b3a890d276" ] }, "required": true }, { "name": "user_ids", "in": "query", "schema": { "type": "string", "maxLength": 3699, "description": "Comma-separated internal user UUIDs, 1 to 100 unique IDs." }, "required": true }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Inclusive start timestamp, with Z or a numeric timezone offset." }, "required": true }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Exclusive end timestamp, with Z or a numeric timezone offset." }, "required": true } ], "security": [ { "OrganizationApiKey": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "TenantUserUsage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUsage" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Read usage in USD for up to 100 users within one Tenant over a positive time range no longer than 93 days. start is inclusive and end is exclusive. Supply ISO 8601 timestamps with an explicit timezone and at most millisecond precision. Only Organization API keys and organization owners or developers may read usage. Missing and out-of-scope user IDs are omitted. Existing users with no settled replies in the range return zero. Results are computed at request time from retained settled replies. Drafts and deleted conversations are excluded, and older replies without saved costs use current rates.", "summary": "Get TenantUser usage" } }, "/api/v1/organization": { "get": { "tags": [ "organization" ], "operationId": "getOrganization", "parameters": [], "security": [ { "OrganizationApiKey": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "Organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Return the id, name, and slug of the Organization that owns the credential. Accepts an organization API key or organization-management JWT, including a viewer's. Tenant JWTs are forbidden.", "summary": "Get the current Organization" } }, "/api/v1/threads": { "get": { "tags": [ "threadDirectory" ], "operationId": "listThreads", "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000]*$", "description": "Case-insensitive literal substring of the conversation title. Trimmed, blank means no search." }, "required": false }, { "name": "filter[tenant_id]", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "DirectoryThreadPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryThreadPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "List nonempty conversations by activity, Tenant ID and thread ID descending. q searches titles as a case-insensitive literal substring. filter[tenant_id] narrows the verified scope. Keep filters unchanged when reusing cursors. This is a live listing, not a snapshot.", "summary": "List conversations for administration" } }, "/api/v1/tenants/{tenantId}/threads/{id}/messages": { "get": { "tags": [ "threadDirectory" ], "operationId": "listThreadMessages", "parameters": [ { "name": "tenantId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "DirectoryThreadHistoryPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryThreadHistoryPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Read conversation history for administration" } }, "/api/v1/chat/files": { "post": { "tags": [ "chat" ], "operationId": "uploadChatFile", "parameters": [], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "UploadedChatFile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedChatFile" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Upload a file before sending a message using a synchronized tenant user JWT. The returned fileId is private to the uploader until sending attaches it to a message. Send it as source: { type: 'file', value: fileId }. Uploads do not expire. Maximum request size: 32 MiB.", "summary": "Upload a chat file", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "document" ] }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "data" ] }, "value": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "type", "value", "mimeType" ], "additionalProperties": false }, "metadata": { "type": "object", "properties": { "filename": { "type": "string" } }, "required": [ "filename" ], "additionalProperties": false } }, "required": [ "type", "source", "metadata" ], "additionalProperties": false } } }, "required": true } }, "get": { "tags": [ "chat" ], "operationId": "getThreadAttachment", "parameters": [ { "name": "threadId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "name": "tenantId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "name": "fileId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "filename", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "delivery", "in": "query", "schema": { "type": "string", "enum": [ "direct" ] }, "required": false } ], "security": [ { "OrganizationApiKey": [] }, { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "Success", "content": { "*/*": { "schema": { "type": "string", "format": "binary" }, "x-effect-stream": { "encoding": "uint8array" } } }, "headers": { "content-disposition": { "schema": { "type": "string" }, "required": true }, "content-length": { "schema": { "type": "string" }, "required": true } } }, "204": { "description": "", "headers": { "location": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Pass the fileId from a saved message, its threadId, and an optional download filename. Tenant JWTs require current conversation membership. Administrative reads also pass tenantId and require directory-read permission through an Organization API key, Organization-management JWT, or signed Tenant admin JWT. Send X-File-Preview: true for a cached thumbnail, or 204 when unavailable. Only the uploader's unsent previews may omit threadId. Original proxied downloads verify stored bytes. Request delivery=direct to receive 204 with a short-lived S3 URL in Location after authorization. A preview may still return 204 without Location when unavailable. Fetch storage URLs without application credentials and do not cache these capability responses.", "summary": "Download a chat file" } }, "/api/v1/chat": { "post": { "tags": [ "chat" ], "operationId": "runChat", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatSubmissionReceipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSubmissionReceiptEncoded" } }, "text/event-stream": { "schema": { "type": "string", "format": "binary" }, "x-effect-stream": { "encoding": "uint8array" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Save one new user message and stream an AG-UI agent run for a conversation participant using a synchronized tenant user JWT. An optional Idempotency-Key retains acceptance for 24 hours. An identical retry returns an application/json admission receipt without generation. Changed input under the same key returns 400 and simultaneous use returns 409. HTTP failures before streaming use AstralBeamApiError. Once streaming starts, failures use RUN_ERROR events. Submit tool results to the conversation's tool-results endpoint. Disconnecting cancels the foreground run and preserves saved history. Limited to 20 new turns per minute per organization, tenant, and user.", "summary": "Run chat", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRunInput" } } }, "required": true } } }, "/api/v1/chat/config": { "get": { "tags": [ "chat" ], "operationId": "getChatConfig", "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string" }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatConfiguration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConfiguration" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Read the selected agent's attachment grant using a tenant user JWT. Omit agentId to use the organization's default agent. Client settings may narrow this grant, never widen it.", "summary": "Get chat capabilities" } }, "/api/v1/chat/usage": { "get": { "tags": [ "chat" ], "operationId": "getChatUsage", "parameters": [ { "name": "threadId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatUsage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatUsage" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Read the usage limits that apply to the current tenant user and how much of each is used, using a tenant user JWT. Amounts and usage are decimal strings, in tokens or US dollars. resetsAt is null until usage opens a window. Pass the threadId of a conversation you participate in to include per-conversation limits.", "summary": "Get usage limits" } }, "/api/v1/chat/threads": { "post": { "tags": [ "chatThreads" ], "operationId": "createChatThread", "parameters": [], "security": [ { "astralBeamToken": [] } ], "responses": { "201": { "description": "ChatThread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatThreadEncoded" } } }, "headers": { "location": { "schema": { "type": "string" }, "required": true } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Create a saved conversation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatThreadInputEncoded" } } }, "required": true } }, "get": { "tags": [ "chatThreads" ], "operationId": "listChatThreads", "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000]*$", "description": "Case-insensitive literal substring of name or external_id. Trimmed, blank means no search." }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatThreadPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatThreadPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "List your conversations" } }, "/api/v1/chat/threads/{id}": { "get": { "tags": [ "chatThreads" ], "operationId": "getChatThread", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatThread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatThreadEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Get a saved conversation" }, "patch": { "tags": [ "chatThreads" ], "operationId": "updateChatThread", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatThread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatThreadEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Rename a conversation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatThreadInputEncoded" } } }, "required": true } }, "delete": { "tags": [ "chatThreads" ], "operationId": "deleteChatThread", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "expected_version", "in": "query", "schema": { "type": "string" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "204": { "description": "" }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Delete a conversation" } }, "/api/v1/chat/threads/{id}/messages": { "get": { "tags": [ "chatThreads" ], "operationId": "listChatMessages", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatHistoryPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatHistoryPageEncoded" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Read conversation history" } }, "/api/v1/chat/threads/{id}/participants": { "get": { "tags": [ "chatThreads" ], "operationId": "listChatParticipants", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatParticipantPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatParticipantPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "List conversation participants" } }, "/api/v1/chat/threads/{id}/tenant-users": { "get": { "tags": [ "chatThreads" ], "operationId": "searchChatTenantUsers", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20, "description": "Positive integer, default 20. Values above 100 are accepted and capped. page_after and page_before are mutually exclusive." }, "required": false }, { "name": "page_after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "page_before", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "required": false }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000]*$", "description": "Case-insensitive literal substring of name or external_id. Trimmed, blank means no search." }, "required": false } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatTenantUserPage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTenantUserPage" } } }, "headers": { "link": { "schema": { "type": "string" }, "required": false } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Requires a conversation manager. Searches names and external IDs within the conversation's Tenant. Returns only identity and display fields, without user metadata or administrative flags.", "summary": "Search same-Tenant users for sharing" } }, "/api/v1/chat/threads/{id}/participants/{tenantUserId}": { "put": { "tags": [ "chatThreads" ], "operationId": "setChatParticipant", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "tenantUserId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "ChatParticipant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatParticipantEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Add a participant or change their role", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetChatParticipantInputEncoded" } } }, "required": true } }, "delete": { "tags": [ "chatThreads" ], "operationId": "removeChatParticipant", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "tenantUserId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "expected_version", "in": "query", "schema": { "type": "string" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "204": { "description": "" }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Remove a conversation participant" } }, "/api/v1/chat/threads/{id}/tool-results": { "post": { "tags": [ "chatThreads" ], "operationId": "resolveChatToolResult", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ {}, { "$ref": "#/components/schemas/ChatToolResultReceiptEncoded" } ] } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "summary": "Submit a pending tool result", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveChatToolResultInputEncoded" } } }, "required": true } } }, "/api/v1/me": { "post": { "tags": [ "currentUser" ], "operationId": "getCurrentUser", "parameters": [], "security": [ { "astralBeamToken": [] }, { "organizationToken": [] } ], "responses": { "200": { "description": "CurrentUser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUser" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "description": "Use a tenant JWT to upsert its own Tenant and TenantUser atomically, without requiring admin authority. Supplied names and metadata replace stored values, omitted profile fields and admin are preserved, and an explicit admin claim updates stored admin. An organization JWT returns existing user membership and the current database role without provisioning identities. API keys and cookies are not accepted. Limited to 100 requests per five minutes per identity.", "summary": "Get the current user" } }, "/api/v1/me/mcp/catalog": { "get": { "tags": [ "personalMcp" ], "operationId": "personalMcp.getCatalog", "parameters": [], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerEncoded" } }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/McpConnectionEncoded" } } }, "required": [ "servers", "connections" ], "additionalProperties": false } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } } } }, "/api/v1/me/mcp/connections": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.createConnection", "parameters": [], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "McpConnection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConnectionEncoded" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_server_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" } }, "required": [ "mcp_server_id" ], "additionalProperties": false } } }, "required": true } } }, "/api/v1/me/mcp/connections/{id}/headers": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.setHeaders", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "204": { "description": "" }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lock_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "headers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192 } } }, "required": [ "lock_version", "headers" ], "additionalProperties": false } } }, "required": true } } }, "/api/v1/me/mcp/connections/{id}": { "delete": { "tags": [ "personalMcp" ], "operationId": "personalMcp.disconnectConnection", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "204": { "description": "" }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } } } }, "/api/v1/me/mcp/connections/{id}/test": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.testConnection", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "tool_count" ], "additionalProperties": false } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } } } }, "/api/v1/me/mcp/connections/{id}/authorize": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.authorizeConnection", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "attempt": { "type": "object", "properties": { "organization_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "tenant_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "connection_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" } }, "required": [ "organization_id", "tenant_id", "id", "connection_id" ], "additionalProperties": false }, "popup_url": { "type": "string" } }, "required": [ "attempt", "popup_url" ], "additionalProperties": false } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } } } }, "/api/v1/me/mcp/connections/{id}/oauth/bind": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.bindBrowser", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "204": { "description": "" }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string" } }, "required": [ "attempt_id", "challenge" ], "additionalProperties": false } } }, "required": true } } }, "/api/v1/me/mcp/connections/{id}/oauth/complete": { "post": { "tags": [ "personalMcp" ], "operationId": "personalMcp.completeAuthorization", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "astralBeamToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "400": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "401": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "403": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "404": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "409": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "413": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "415": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "422": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "429": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "500": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } }, "503": { "description": "AstralBeamApiError", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AstralBeamApiError" } } }, "headers": { "retry-after": { "schema": { "type": "string" }, "required": false }, "www-authenticate": { "schema": { "type": "string" }, "required": false } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attempt_id": { "type": "string", "format": "uuid" } }, "required": [ "attempt_id" ], "additionalProperties": false } } }, "required": true } } } }, "components": { "schemas": { "AstralBeamApiError": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "usage_limit": { "type": "object", "properties": { "name": { "type": "string" }, "resets_at": { "type": "string" } }, "required": [ "name", "resets_at" ], "additionalProperties": false, "description": "The usage limit a 429 reached, by its display name, and when it resets." }, "reference": { "type": "string", "description": "Identifies the server log entry of an internal error. Quote it for support." } }, "required": [ "type", "title", "status", "detail" ], "additionalProperties": false }, "McpConnectionEncoded": { "type": "object", "properties": { "organization_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "tenant_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "mcp_server_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "lock_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auth_state": { "type": "string", "enum": [ "disconnected", "connected", "reauthorization_required" ] } }, "required": [ "organization_id", "tenant_id", "id", "mcp_server_id", "lock_version", "auth_state" ], "additionalProperties": false }, "McpServerEncoded": { "type": "object", "properties": { "organization_id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", "format": "uuid" }, "endpoint_url": { "type": "string" }, "auth_kind": { "anyOf": [ { "type": "string", "enum": [ "none", "static_headers", "oauth" ] }, { "type": "null" } ] }, "header_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "organization_id", "id", "endpoint_url", "auth_kind", "header_names" ], "additionalProperties": false }, "CurrentUser": { "anyOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "tenant" ] }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "tenant": { "$ref": "#/components/schemas/TenantRecordEncoded" }, "user": { "$ref": "#/components/schemas/TenantUserRecordEncoded" } }, "required": [ "scope", "organization", "tenant", "user" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "organization" ] }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false } }, "required": [ "scope", "organization", "user" ], "additionalProperties": false } ] }, "TenantUserRecordEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" }, "admin": { "type": "boolean" } }, "required": [ "id", "external_id", "name", "metadata", "created_at", "updated_at", "tenant_id", "admin" ], "additionalProperties": false, "title": "TenantUserRecord", "description": "Persisted TenantUser. Stored admin does not grant or revoke signed JWT authority.", "examples": [ { "id": "019eed6a-d1c0-7543-b892-608cb6e174da", "external_id": "user-7", "name": "Alex Morgan", "metadata": { "role": "dispatcher", "department": "operations" }, "created_at": "2026-06-22T09:30:00.000Z", "updated_at": "2026-06-22T09:30:00.000Z", "tenant_id": "019eed68-fd00-7c42-9a61-53b3a890d276", "admin": false } ] }, "TenantRecordEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "name", "metadata", "created_at", "updated_at" ], "additionalProperties": false, "title": "TenantRecord", "description": "Persisted Tenant; id is internal, external_id is the customer's exact identity.", "examples": [ { "id": "019eed68-fd00-7c42-9a61-53b3a890d276", "external_id": "customer-42", "name": "Acme Logistics", "metadata": { "plan": "pro", "region": "eu-west-1" }, "created_at": "2026-06-22T09:30:00.000Z", "updated_at": "2026-06-22T09:30:00.000Z" } ] }, "ChatToolResultReceiptEncoded": { "type": "object", "properties": { "thread_id": { "type": "string", "format": "uuid" }, "accepted_message_id": { "type": "string", "format": "uuid" }, "thread_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage_limit": { "type": "object", "properties": { "name": { "type": "string" }, "resets_at": { "type": "string" } }, "required": [ "name", "resets_at" ], "additionalProperties": false } }, "required": [ "thread_id", "accepted_message_id", "thread_version" ], "additionalProperties": false }, "ResolveChatToolResultInputEncoded": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "source_message_id": { "type": "string", "format": "uuid" }, "source_part_id": { "type": "string", "minLength": 1 }, "response_target_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "succeeded", "failed", "skipped", "unknown" ] }, "output": {} }, "required": [ "source_message_id", "source_part_id", "response_target_id", "outcome", "output" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "client_id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "parent_run_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "results", "client_id" ], "additionalProperties": false }, "ChatParticipantEncoded": { "type": "object", "properties": { "tenant_user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "viewer", "member", "manager" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "tenant_user_id", "role", "name", "external_id", "email" ], "additionalProperties": false }, "SetChatParticipantInputEncoded": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "viewer", "member", "manager" ] }, "expected_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "role", "expected_version" ], "additionalProperties": false }, "ChatTenantUserPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChatTenantUserEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false }, "ChatTenantUserEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "external_id", "email" ], "additionalProperties": false }, "ChatParticipantPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChatParticipantEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false }, "ChatHistoryPageEncoded": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "tool" ] }, "state": { "type": "string", "enum": [ "draft", "complete", "interrupted" ] }, "parent_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parts": { "type": "array", "items": { "type": "object" } }, "author_tenant_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source_assistant_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source_tool_part_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "role", "state", "parent_message_id", "parts", "author_tenant_user_id", "source_assistant_message_id", "source_tool_part_id", "response_target_id", "created_at" ], "additionalProperties": false } }, "thread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "current_leaf_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "viewer", "member", "manager" ] }, "writer_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "agent_id", "version", "current_leaf_message_id", "role", "writer_active", "created_at", "updated_at" ], "additionalProperties": false }, "pending_interactions": { "type": "array", "items": { "type": "object", "properties": { "source_message_id": { "type": "string", "format": "uuid" }, "source_part_id": { "type": "string" }, "response_target_id": { "type": "string" }, "tool_call_id": { "type": "string" }, "target_tenant_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "target_client_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "execution_location": { "type": "string", "enum": [ "server_api", "sandbox", "browser" ] } }, "required": [ "source_message_id", "source_part_id", "response_target_id", "tool_call_id", "target_tenant_user_id", "target_client_id", "execution_location" ], "additionalProperties": false } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "messages", "thread", "pending_interactions", "page_after", "page_before" ], "additionalProperties": false }, "ChatThreadEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "current_leaf_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "viewer", "member", "manager" ] }, "writer_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "agent_id", "version", "current_leaf_message_id", "role", "writer_active", "created_at", "updated_at" ], "additionalProperties": false }, "UpdateChatThreadInputEncoded": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "expected_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "title", "expected_version" ], "additionalProperties": false }, "ChatThreadPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChatThreadEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false }, "CreateChatThreadInputEncoded": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "agent_id": { "type": "string" } }, "additionalProperties": false }, "ChatUsage": { "type": "object", "properties": { "usageLimits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "global", "tenant", "tenant_user", "thread" ] }, "metric": { "type": "string", "enum": [ "tokens", "spend" ] }, "amount": { "type": "string" }, "used": { "type": "string" }, "resetsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "scope", "metric", "amount", "used", "resetsAt" ], "additionalProperties": false } } }, "required": [ "usageLimits" ], "additionalProperties": false }, "ChatConfiguration": { "type": "object", "properties": { "capabilities": { "type": "object", "properties": { "attachments": { "type": "boolean" } }, "required": [ "attachments" ], "additionalProperties": false } }, "required": [ "capabilities" ], "additionalProperties": false }, "ChatSubmissionReceiptEncoded": { "type": "object", "properties": { "thread_id": { "type": "string", "format": "uuid" }, "accepted_message_id": { "type": "string", "format": "uuid" }, "thread_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "thread_id", "accepted_message_id", "thread_version" ], "additionalProperties": false }, "ChatRunInput": { "type": "object", "properties": { "threadId": { "type": "string", "format": "uuid" }, "runId": { "type": "string" }, "messages": { "type": "array" }, "tools": { "type": "array" }, "context": { "type": "array" }, "forwardedProps": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" } }, "required": [ "clientId" ], "allOf": [ { "type": "object", "additionalProperties": {} } ] }, "state": {}, "parentRunId": { "type": "string" } }, "required": [ "threadId", "runId", "messages", "tools", "context", "forwardedProps" ], "additionalProperties": false, "description": "AG-UI RunAgentInput, validated by TanStack AI. Use the saved conversation UUID as threadId, send exactly one new user message and set forwardedProps.clientId. The server appends to the current history path, loads saved context, and uses the conversation's selected agent. Replacement history, resume entries, and systemPrompt are rejected. forwardedProps.debug is development-only. Maximum request size: 32 MiB.", "examples": [ { "threadId": "019a0000-0000-7000-8000-000000000004", "runId": "run-7", "messages": [ { "id": "message-1", "role": "user", "content": "Hello!" } ], "tools": [], "context": [], "forwardedProps": { "clientId": "019a0000-0000-7000-8000-000000000003" } } ] }, "UploadedChatFile": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "mimeType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "fileId", "mimeType", "byteSize" ], "additionalProperties": false }, "DirectoryThreadHistoryPage": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessageEncoded" } }, "thread": { "$ref": "#/components/schemas/DirectoryThreadEncoded" }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "messages", "thread", "page_after", "page_before" ], "additionalProperties": false }, "DirectoryThreadEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tenant_external_id": { "type": "string" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "type": "string" } }, "required": [ "name", "external_id" ], "additionalProperties": false } }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "tenant_name", "tenant_external_id", "participants", "title", "agent_id", "created_at", "updated_at" ], "additionalProperties": false }, "ChatMessageEncoded": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "tool" ] }, "state": { "type": "string", "enum": [ "draft", "complete", "interrupted" ] }, "parent_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parts": { "type": "array", "items": { "type": "object" } }, "author_tenant_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source_assistant_message_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source_tool_part_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "role", "state", "parent_message_id", "parts", "author_tenant_user_id", "source_assistant_message_id", "source_tool_part_id", "response_target_id", "created_at" ], "additionalProperties": false }, "DirectoryThreadPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryThreadEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "description": "Editable dashboard URL segment. Use id, not slug, as the stable identity." } }, "required": [ "id", "name", "slug" ], "additionalProperties": false, "examples": [ { "id": "019eed68-fd00-7c42-9a61-53b3a890d276", "name": "Acme", "slug": "acme" } ] }, "TenantUserUsage": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "tenant_user_id": { "type": "string", "format": "uuid" }, "cost_usd": { "type": "string", "description": "USD total from settled saved assistant replies. Uses saved resolved or provider-reported costs when available, otherwise current configured model-token rates. Drafts and deleted conversations are excluded. Unpriceable replies contribute zero for now, and users with no settled replies return zero.", "examples": [ "0.012345", "0" ] } }, "required": [ "tenant_user_id", "cost_usd" ], "additionalProperties": false } } }, "required": [ "start", "end", "items" ], "additionalProperties": false }, "UpdateTenantUserInput": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to null on creation. Send null to clear the name." }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved. Defaults to {} on creation. Updates replace the entire object." }, "admin": { "type": "boolean", "description": "Defaults to false on creation. Stored admin does not change signed JWT authority." } }, "additionalProperties": false, "examples": [ { "name": "Alex Morgan-Smith" }, { "name": null, "metadata": {} } ], "minProperties": 1 }, "CreateTenantUserInput": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your stable external identity. Exact and case-sensitive; whitespace is preserved. Immutable after creation." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to null on creation. Send null to clear the name." }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved. Defaults to {} on creation. Updates replace the entire object." }, "admin": { "type": "boolean", "description": "Defaults to false on creation. Stored admin does not change signed JWT authority." } }, "required": [ "external_id" ], "additionalProperties": false, "examples": [ { "external_id": "user-7", "name": "Alex Morgan", "metadata": { "role": "dispatcher", "department": "operations" }, "admin": false }, { "external_id": "user-7" } ] }, "TenantUserPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUserRecordEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false, "description": "Live keyset page in ascending ID order within one Tenant. Pass either non-null continuation value as the same-named request parameter.", "examples": [ { "items": [], "page_after": null, "page_before": null } ] }, "UpdateTenantInput": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to null on creation. Send null to clear the name." }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved. Defaults to {} on creation. Updates replace the entire object." } }, "additionalProperties": false, "examples": [ { "metadata": { "plan": "enterprise", "region": "eu-west-1" } }, { "name": null, "metadata": {} } ], "minProperties": 1 }, "CreateTenantInput": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your stable external identity. Exact and case-sensitive; whitespace is preserved. Immutable after creation." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to null on creation. Send null to clear the name." }, "metadata": { "type": "object", "description": "Customer-defined JSON object; keys are preserved. Defaults to {} on creation. Updates replace the entire object." } }, "required": [ "external_id" ], "additionalProperties": false, "examples": [ { "external_id": "customer-42", "name": "Acme Logistics", "metadata": { "plan": "pro", "region": "eu-west-1" } }, { "external_id": "customer-42" } ] }, "TenantPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantRecordEncoded" } }, "page_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_after to fetch the next page; null means no next page." }, "page_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as page_before to fetch the previous page; null means no previous page." } }, "required": [ "items", "page_after", "page_before" ], "additionalProperties": false, "description": "Live keyset page. Pass either non-null continuation value as the same-named request parameter.", "examples": [ { "items": [], "page_after": null, "page_before": null } ] }, "DocumentationSearch": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string" }, "page": { "type": "string" }, "heading": { "type": "string" }, "text": { "type": "string" } }, "required": [ "path", "url", "page", "heading", "text" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } }, "securitySchemes": { "OrganizationApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Full decorated organization API key." }, "astralBeamToken": { "type": "http", "scheme": "bearer", "description": "Chat JWT. Tenant resource APIs also accept a full organization API key here." }, "organizationToken": { "type": "http", "scheme": "bearer", "description": "Organization-management JWT delegates the selected member's current database permissions: owners/developers read and write Tenant resources, viewers read only. The trusted API-key holder selects the member and retains owner-equivalent resource access. Does not authenticate chat or dashboard administration." } } }, "security": [], "tags": [ { "name": "documentation" }, { "name": "tenants", "description": "A Tenant is one of your Organization's customers. Use internal UUID IDs in resource paths and your own customer identity as external_id. External IDs are unique within the organization. Creation returns 201 and Location; reads and updates return 200. PATCH changes only supplied fields. IDs, external IDs, ownership, and timestamps are immutable. Updates use last-write-wins. Responses never expose organization_id; timestamps are ISO-8601 strings. These APIs neither issue tokens nor upsert identities. See [Errors](/docs/api#description/errors) for shared error handling.", "x-displayName": "Tenants" }, { "name": "tenant_users", "description": "A TenantUser is a user of one of your Organization's Tenants, not an employee using the dashboard. All routes use internal UUID tenant_id and user id values. External IDs are unique within the organization and Tenant; the same external user ID may exist in another Tenant. Creation returns 201 and Location; reads and updates return 200. PATCH changes only supplied fields. IDs, external IDs, ownership, and timestamps are immutable; users cannot move between Tenants. Updates use last-write-wins. Responses never expose organization_id; timestamps are ISO-8601 strings. Stored admin does not change signed JWT authority. Creation does not issue tokens or upsert identities. See [Errors](/docs/api#description/errors) for shared error handling.", "x-displayName": "TenantUsers" }, { "name": "organization", "x-displayName": "Organization" }, { "name": "threadDirectory", "description": "Read-only administrative access. Organization API keys and Organization-management JWTs with current directory-read permission can read their Organization. Signed Tenant admins can read only their Tenant. Administrative reads neither create participant grants nor authorize chat actions. Unknown and inaccessible conversations return the same 404. Saved uploads remain readable independently of the current agent configuration. Stored drafts do not imply a live producer." }, { "name": "chat" }, { "name": "chatThreads", "description": "Saved conversations require a tenant user JWT and an identity synchronized through POST /me. Viewers read history, members also send messages and resolve tools, and managers additionally rename, delete, and manage participants. Sharing is limited to the same Tenant. Unknown and inaccessible conversations both return 404. New messages append to the current history path automatically. Metadata and participant changes require the current conversation version. Deleting a conversation stops subsequent writes." }, { "name": "currentUser" }, { "name": "personalMcp" } ], "servers": [ { "url": "/" } ] }