[pull] master from cube-js:master

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: []

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.
 
 </Warning>
 
-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,19 +272,23 @@ 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
 ```
 
 <Info>
 
-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**.
 
 </Info>
 
 ### Path Parameters
 
 - **`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