From 809bc372e46cbfa3063d3b01d0d8680123693a15 Mon Sep 17 00:00:00 2001 From: Pavel Tiunov Date: Sat, 15 Aug 2026 13:08:35 -0700 Subject: [PATCH] docs: document the deployment-scoped Chat API endpoint for the Auto agent (#11566) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: document the deployment-scoped Chat API endpoint for the Auto agent The public Chat API can be addressed by deployment (`/api/v1/public/:account/deployments/:deploymentId/chat/...`) as well as by agent; the deployment form resolves to the deployment's Auto agent. Document both shapes for stream-chat-state and abort, and point at the deployment's API credentials page as the place to copy the URL from. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Cr35TwoTbUhJr9onzbymXs * docs: correct Chat API auth support for the deployment-scoped endpoint The deployment form is served only through the Cube token exchange — that exchange is what resolves the Auto agent, so an API key (which carries no agent) is rejected with 403. Replace the claim that both forms take the same authentication with a support matrix and the concrete failure mode. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Cr35TwoTbUhJr9onzbymXs * docs: qualify Chat API deployment-form auth and cover it in the OpenAPI spec Follow-up on review of the deployment-scoped Chat API docs: - State that the deployment form works only once Cube token auth is enabled (Settings -> Configuration), since that switch is off by default and the URL Cube surfaces in API credentials fails until it is flipped. - Qualify the abort endpoint's auth section the same way, so it no longer contradicts the support matrix two sections above. - Add the deployment-scoped server to the interactive API reference (api-reference/chat.yaml), which previously covered only the agent form. - Drop "the agent's deployment" in the Cube token section, which read oddly for the deployment form where no agent is in the request. - Label the matrix's first header column. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Cr35TwoTbUhJr9onzbymXs * docs: match the OpenAPI deploymentId default to its own example The variable's description points at /d/9 while the default was '1', so the pre-filled playground value disagreed with the example beside it and with the deployment id used in chat-api.mdx. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Cr35TwoTbUhJr9onzbymXs --------- Co-authored-by: Claude Opus 5 --- docs-mintlify/api-reference/chat.yaml | 26 ++++++++-- .../reference/embed-apis/chat-api.mdx | 49 ++++++++++++++++--- 2 files changed, 64 insertions(+), 11 deletions(-) diff --git a/docs-mintlify/api-reference/chat.yaml b/docs-mintlify/api-reference/chat.yaml index 11021cf29cc0c..c3d35a002fdb8 100644 --- a/docs-mintlify/api-reference/chat.yaml +++ b/docs-mintlify/api-reference/chat.yaml @@ -5,12 +5,16 @@ info: description: |- Real-time streaming conversations with Cube Cloud AI agents for analytics and data exploration. Copy the exact Chat API URL from your agent settings - (Admin → Agents → Chat API URL). + (Admin → Agents → Chat API URL), or — to talk to a deployment's Auto agent — + from the deployment's Settings → API credentials → Chat API tab. + + The deployment-scoped base URL accepts only Cube token authentication; an API + key carries no agent, so it cannot resolve the Auto agent. servers: - url: https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId} description: >- - Chat API base URL. Copy the exact URL from your agent settings (Admin → Agents → Chat API - URL). + Agent-scoped base URL — talks to that specific agent. Copy the exact URL from your agent + settings (Admin → Agents → Chat API URL). Accepts an API key or a Cube token. variables: cloudRegion: default: gcp-us-central1 @@ -21,6 +25,22 @@ servers: agentId: default: '1' description: AI agent identifier (Admin → Agents) + - url: https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId} + description: >- + Deployment-scoped base URL — talks to the deployment's Auto agent. Copy the exact URL from + Settings → API credentials → Chat API. Accepts only Cube token authentication, which is + disabled by default (Settings → Configuration → Use Cube authentication for Chat and + embedding APIs). + variables: + cloudRegion: + default: gcp-us-central1 + description: Cloud region identifier + accountName: + default: your-account + description: Your Cube Cloud account/tenant name + deploymentId: + default: '9' + description: Deployment identifier (from the deployment URL, e.g. /d/9) security: - apiKey: [] - cubeToken: [] diff --git a/docs-mintlify/reference/embed-apis/chat-api.mdx b/docs-mintlify/reference/embed-apis/chat-api.mdx index e7b40265f6096..d9f693db3b92d 100644 --- a/docs-mintlify/reference/embed-apis/chat-api.mdx +++ b/docs-mintlify/reference/embed-apis/chat-api.mdx @@ -11,14 +11,40 @@ The Chat API is available on [Premium and Enterprise plans](https://cube.dev/pri ## Endpoint +The endpoint can be addressed either by agent or by deployment. -The endpoint has the following structure: +Addressed by agent, it talks to that specific agent: ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state ``` -Copy the exact Chat API URL from your agent settings (**Chat API URL** field) in **Admin → Agents**. +Copy the exact URL from your agent settings (**Chat API URL** field) in **Admin → Agents**. + +Addressed by deployment, it talks to the deployment's Auto agent — the agent +used when no specific one is selected: + +```text +https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state +``` + +Copy the exact URL from the deployment's **Settings → API credentials → Chat API** +tab, also reachable from the **Chat** entry on the deployment's **Status** page. + +The two forms differ in which authentication they accept: + +| URL form | [API key](#api-key-authentication) | [Cube token](#cube-token-authentication) | +|---|:---:|:---:| +| `/agents/{agentId}/…` | ✓ | ✓ | +| `/deployments/{deploymentId}/…` | — | ✓ | + +The deployment form is served **only** through the Cube token exchange, which is +what resolves the Auto agent — an API key carries no agent, so a request without +`{agentId}` in the path is rejected with `403 agentId is required for Api-Key +authentication`. Because [Cube token authentication](#cube-token-authentication) +is disabled by default, the deployment form works only once it is enabled in +**Settings** → **Configuration** → **Use Cube authentication for Chat and +embedding APIs**. Request body and streaming response are identical for both. ## Overview @@ -133,8 +159,8 @@ and the `X-Cube-Auth-Token` header is ignored. Send exactly one of the two. -To be accepted by the Chat API, the token must be valid for the agent's -deployment and include the following claims in its payload: +To be accepted by the Chat API, the token must be valid for the deployment and +include the following claims in its payload: - `externalId` (required) — unique identifier for the external user. Normalized to lowercase, so ids that differ only in casing map to the same @@ -246,11 +272,14 @@ The attributes passed during session generation become available as `userAttribu ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state +https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state ``` -Copy the complete Chat API URL from your agent settings (**Chat API URL** field) in **Admin → Agents**. +Copy the complete Chat API URL from your agent settings (**Chat API URL** field) +in **Admin → Agents**, or — for the deployment's Auto agent — from +**Settings → API credentials → Chat API**. @@ -258,7 +287,8 @@ Copy the complete Chat API URL from your agent settings (**Chat API URL** field) - **`cloudRegion`** (string): The cloud region identifier (e.g., "gcp-us-central1") - **`accountName`** (string, required): The account identifier (e.g., "acme"). It is in your account URL, e.g. https://acme.cubecloud.dev -- **`agentId`** (string, required): The AI agent identifier (e.g., "1"). You can find it in **Admin → Agents → Click on Agent row in the table**. +- **`agentId`** (string, required for the agent form): The AI agent identifier (e.g., "1"). You can find it in **Admin → Agents → Click on Agent row in the table**. +- **`deploymentId`** (string, required for the deployment form): The deployment identifier (e.g., "9"). It is in the deployment URL, e.g. https://acme.cubecloud.dev/d/9. Resolves to the deployment's Auto agent. ### Request Body @@ -931,16 +961,19 @@ response. ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/abort +https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/abort ``` The abort URL is derived from the Chat API URL by replacing `/stream-chat-state` -with `/abort`. +with `/abort` — for whichever form, agent or deployment, you used to start the +stream. ### Authentication Supports the same authentication methods as the Chat API: an [API key](#api-key-authentication) or, when enabled for your deployment, a -[Cube token](#cube-token-authentication). +[Cube token](#cube-token-authentication). As with `stream-chat-state`, the +`/deployments/{deploymentId}/…` form accepts only a Cube token. ### Request Body