> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Cube's HTTP APIs — query your data with the Core Data API, stream agent conversations with the AI API, and manage Cube with the Platform API.

Cube exposes three HTTP API families, each for a different job and with slightly
different authentication:

| API | What it's for | Authentication |
| - | - | - |
| **Core Data API** | Query your data model over HTTP — run queries (`/v1/load`) and read metadata (`/v1/meta`) | Cube API token (a JWT) sent **directly** in the `Authorization` header — no prefix |
| **AI API** | Stream conversations with Cube AI agents (`/chat/stream-chat-state`) | Cube API key with the **`Api-Key`** prefix |
| **Platform API** | Manage Cube — deployments, data models, reports, workbooks, users, policies, and more | **`Bearer`** prefix for REST and SCIM 2.0 |

The exact header for each is shown above. The Platform and SCIM schemes are
detailed on the [Authentication](https://docs.cube.dev/api-reference/authentication.md) page; the Core
Data and AI headers are also documented on their own reference pages.

## Available endpoints

Each API family has its own base URL — copy the exact host from the Cube
interface where noted. Only HTTPS is accepted, and every request must be
authenticated (see [Authentication](https://docs.cube.dev/api-reference/authentication.md)).

### Core Data API

Base URL — your deployment's data API host (the `/cubejs-api` base path is configurable):

```text theme={"dark"}
https://{deployment}.{region}.cubecloudapp.dev/cubejs-api
```

| Endpoint | Path |
| - | - |
| [JSON query](https://docs.cube.dev/api-reference/data/json-query.md) | `POST /v1/load` |
| [SQL query](https://docs.cube.dev/api-reference/data/sql-query.md) | `POST /v1/cubesql` |
| [Metadata](https://docs.cube.dev/api-reference/data/load-metadata.md) | `GET /v1/meta` |

### AI API

Base URL — your agent's Chat API URL (copy it from **Admin → Agents → Chat API URL**):

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}
```

| Endpoint | Path |
| - | - |
| [Stream chat state](https://docs.cube.dev/api-reference/chat/stream-chat-state.md) | `POST /chat/stream-chat-state` |

### Platform API

Base URL — your tenant host:

```text theme={"dark"}
https://{tenant}.cubecloud.dev
```

Endpoints live under three path prefixes on that host, all taking the same token:

| Prefix | What it covers |
| - | - |
| `/api/v1/…` | Management of deployments, workspace content, users, policies, and embedding |
| `/build/api/v1/…` | Data model authoring — files, uploads, dev mode, and branches. Routed to the build workers that own a deployment's data model. |
| `/api/scim/v2/…` | SCIM 2.0 user and group provisioning |

Resources by entity:

| Entity | Resource | Version |
| - | - | - |
| [Deployments](https://docs.cube.dev/api-reference/deployments/get-deployments.md) | `/api/v1/deployments` | v1 |
| [Deployment Creation](https://docs.cube.dev/api-reference/deployment-creation/create-a-deployment-with-an-empty-starter-project-and-trigger-its-first-build.md) | `/build/api/v1/deployments` | v1 |
| [Environments](https://docs.cube.dev/api-reference/environments/get-deployment-environments.md) | `/api/v1/deployments/{deploymentId}/environments` | v1 |
| [Env Variables](https://docs.cube.dev/api-reference/env-variables/list-environment-variables%2C-including-the-database-connection-settings) | `/api/v1/deployments/{deploymentId}/env-vars` | v1 |
| [Regions](https://docs.cube.dev/api-reference/regions/list-regions.md) | `/api/v1/regions` | v1 |
| [Data Model](https://docs.cube.dev/api-reference/data-model/list-a-deployments-branches.md) | `/build/api/v1/deployments/{deploymentId}/*` | v1 |
| [Data Model Uploads](https://docs.cube.dev/api-reference/data-model-uploads/content-hashes-of-the-current-data-model-files-for-upload-diffing.md) | `/build/api/v1/deployments/{deploymentId}/data-model/*` | v1 |
| [GitHub](https://docs.cube.dev/api-reference/github/list-repositories-accessible-to-a-github-app-installation.md) | `/api/v1/github/*` | v1 |
| [GitHub Connection](https://docs.cube.dev/api-reference/github-connection/connect-a-deployment-to-a-github-repository-and-trigger-a-build.md) | `/build/api/v1/deployments/{deploymentId}/github/connect` | v1 |
| [dbt Sync](https://docs.cube.dev/api-reference/dbt-sync/list-dbt-syncs-for-a-deployment.md) | `/api/v1/deployments/{deploymentId}/dbt-sync` | v1 |
| [Databricks Metric View Publication](https://docs.cube.dev/api-reference/databricks-metric-view-publication/start-a-databricks-metric-view-publication-preview.md) | `/api/v1/deployments/{deploymentId}/databricks-metric-view-previews` | v1 |
| [Databricks Metric View Integration](https://docs.cube.dev/api-reference/databricks-metric-view-integration/get-databricks-metric-view-publication-settings.md) | `/api/v1/deployments/{deploymentId}/databricks-metric-view-integrations/{dataSourceName}` | v1 |
| [Snowflake Semantic View Sync](https://docs.cube.dev/api-reference/snowflake-semantic-view-sync/pull-snowflake-semantic-views-into-cube.md) | `/api/v1/deployments/{deploymentId}/snowflake-semantic-view-{pulls,syncs}` | v1 |
| [Folders](https://docs.cube.dev/api-reference/folders/list-folders.md) | `/api/v1/deployments/{deploymentId}/folders` | v1 |
| [Reports](https://docs.cube.dev/api-reference/reports/list-reports.md) | `/api/v1/deployments/{deploymentId}/reports` | v1 |
| [External Documents](https://docs.cube.dev/api-reference/external-documents/prove-the-caller-has-an-external-spreadsheet-open.md) | `/api/v1/external-documents/{externalWorkbookId}/*` | v1 |
| [Workbooks](https://docs.cube.dev/api-reference/workbooks/get-workbooks.md) | `/api/v1/deployments/{deploymentId}/workbooks` | v1 |
| [Workbook Promotions](https://docs.cube.dev/api-reference/workbook-promotions/get-workbook-promotion-provenance.md) | `/api/v1/deployments/{deploymentId}/workbooks/{workbookId}/*` | v1 |
| [Dashboard Exports](https://docs.cube.dev/api-reference/dashboard-exports/export-a-dashboard-as-png-or-pdf.md) | `/api/v1/deployments/{deploymentId}/dashboard-exports` | v1 |
| [Notifications](https://docs.cube.dev/api-reference/notifications/list-scheduled-notifications.md) | `/api/v1/deployments/{deploymentId}/notifications` | v1 |
| [Scheduled Tasks](https://docs.cube.dev/api-reference/scheduled-tasks/list-scheduled-tasks.md) | `/api/v1/deployments/{deploymentId}/scheduled-tasks` | v1 |
| [Workspace](https://docs.cube.dev/api-reference/workspace/list-shared-workspace-items.md) | `/api/v1/deployments/{deploymentId}/*` | v1 |
| [Agents](https://docs.cube.dev/api-reference/agents/get-agent-defaults.md) | `/api/v1/deployments/{deploymentId}/*` | v1 |
| [Users](https://docs.cube.dev/api-reference/users/update-my-settings.md) | `/api/v1/users/me/settings` | v1 |
| [Users Admin](https://docs.cube.dev/api-reference/users-admin/create-user.md) | `/api/v1/users` | v1 |
| [API Keys](https://docs.cube.dev/api-reference/api-keys/list-api-keys.md) | `/api/v1/api-keys` | v1 |
| [Roles](https://docs.cube.dev/api-reference/roles/list-custom-roles.md) | `/api/v1/roles` | v1 |
| [User Attributes](https://docs.cube.dev/api-reference/user-attributes/get-user-attributes.md) | `/api/v1/user-attributes` | v1 |
| [User Attribute Values](https://docs.cube.dev/api-reference/user-attribute-values/upsert-user-attribute-value.md) | `/api/v1/user-attribute-values` | v1 |
| [Tenant Settings](https://docs.cube.dev/api-reference/tenant-settings/get-tenant-settings.md) | `/api/v1/tenant/settings` | v1 |
| [OAuth Integrations](https://docs.cube.dev/api-reference/oauth-integrations/list-oauth-integrations.md) | `/api/v1/oauth-integrations` | v1 |
| [User OAuth Tokens](https://docs.cube.dev/api-reference/user-oauth-tokens/list-user-oauth-tokens.md) | `/api/v1/user-oauth-tokens` | v1 |
| [OIDC Token Configs](https://docs.cube.dev/api-reference/oidc-token-configs/list-oidc-token-configs.md) | `/api/v1/oidc-token-configs` | v1 |
| [App Theme](https://docs.cube.dev/api-reference/app-theme/get-app-config.md) | `/api/v1/app-config` | v1 |
| [Embed](https://docs.cube.dev/api-reference/embed/get-an-embeddable-dashboard.md) | `/api/v1/embed/*` | v1 |
| [Embed Tenants](https://docs.cube.dev/api-reference/embed-tenants/list-embed-tenants.md) | `/api/v1/embed-tenants` | v1 |
| [Dashboard Embed Access](https://docs.cube.dev/api-reference/dashboard-embed-access/list-workbooks-accessible-to-an-embed-tenant.md) | `/api/v1/deployments/{deploymentId}/*` | v1 |
| [Usage Analytics](https://docs.cube.dev/api-reference/usage-analytics/issue-a-cube-api-token-for-usage-analytics.md) | `/api/v1/usage-analytics/token` | v1 |
| [OpenAPI Spec](https://docs.cube.dev/api-reference/openapi-spec/get-the-openapi-specification.md) | `/api/v1/spec` | v1 |
| [Audit Log](https://docs.cube.dev/api-reference/audit-log/export-the-audit-log.md) | `/api/v1/audit-logs/export` | v1 |
| [Chat History](https://docs.cube.dev/api-reference/chat-history/list-chat-threads.md) | `/api/v1/deployments/{deploymentId}/chat-history/threads` | v1 |
| [Ossie Conversion](https://docs.cube.dev/api-reference/ossie-conversion/start-an-apache-ossie-conversion.md) | `/api/v1/deployments/{deploymentId}/ossie-conversions` | v1 |
| [Report Deliveries](https://docs.cube.dev/api-reference/report-deliveries/list-report-deliveries.md) | `/api/v1/deployments/{deploymentId}/report-deliveries` | v1 |
| [Users (SCIM)](https://docs.cube.dev/api-reference/scim-users/list-users.md) | `/api/scim/v2/Users` | SCIM 2.0 |
| [Groups (SCIM)](https://docs.cube.dev/api-reference/scim-groups/list-groups.md) | `/api/scim/v2/Groups` | SCIM 2.0 |

## Client libraries

### Core Data API

Query the Core Data API from JavaScript or TypeScript with Cube's JS client,
[`@cubejs-client/core`](https://www.npmjs.com/package/@cubejs-client/core), which
also ships React, Vue, and Angular bindings and a WebSocket transport for
real-time updates. See the [JavaScript SDK](https://docs.cube.dev/reference/javascript-sdk.md) reference
for full usage.

```bash theme={"dark"}
npm install @cubejs-client/core
```

### Platform API

The recommended way to call the Platform API from JavaScript or TypeScript is the
official client, [`@cube-dev/platform-client`](https://www.npmjs.com/package/@cube-dev/platform-client).
It wraps the OpenAPI spec on this site with end-to-end types for every endpoint,
request, and response, plus optional [React Query](https://tanstack.com/query)
bindings.

```bash npm theme={"dark"}
npm install @cube-dev/platform-client
```

```bash yarn theme={"dark"}
yarn add @cube-dev/platform-client
```

```bash pnpm theme={"dark"}
pnpm add @cube-dev/platform-client
```

Create a client with your tenant's base URL and an auth header (see
[Authentication](https://docs.cube.dev/api-reference/authentication.md)), then call any endpoint through
the fully-typed `fetchClient`:

```ts theme={"dark"}
import { createCubePlatformClient } from '@cube-dev/platform-client';

const client = createCubePlatformClient({
  baseUrl: 'https://<tenant>.cubecloud.dev',
  // Returned on every request — provide the Platform API auth header.
  getHeaders: () => ({ Authorization: `Bearer ${process.env.CUBE_API_KEY}` }),
});

const { data, error } = await client.fetchClient.GET('/api/v1/deployments/', {
  params: { query: { first: 50 } },
});

for (const deployment of data?.items ?? []) {
  console.log(deployment.id, deployment.name);
}
```

#### React Query bindings

The `@cube-dev/platform-client/react-query` entry point adds a provider and typed
hooks built on `@tanstack/react-query` (a peer dependency alongside `react`):

```tsx theme={"dark"}
import { createCubePlatformClient } from '@cube-dev/platform-client';
import {
  CubePlatformApiProvider,
  useCubePlatformApiQuery,
} from '@cube-dev/platform-client/react-query';

const client = createCubePlatformClient({ baseUrl, getHeaders });

function App() {
  return (
    <CubePlatformApiProvider client={client}>
      <Deployments />
    </CubePlatformApiProvider>
  );
}

function Deployments() {
  const { data } = useCubePlatformApiQuery('get', '/api/v1/deployments/');
  return <ul>{data?.items.map((d) => <li key={d.id}>{d.name}</li>)}</ul>;
}
```

> [!NOTE]
>
> Schema types are exported as `PlatformApiSchemas` (e.g.
> `PlatformApiSchemas['Deployment']`). See the package
> [`CHANGELOG`](https://docs.cube.dev/api-reference/changelog) for release notes and breaking changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.