Skip to content

Commit 68e9e88

Browse files
keydunovclaude
keydunov
and
claude
authored
docs(api): three API families (Core Data, AI, Platform) + curated public surface (#11041)
* docs(api): add AI Endpoints chat spec to Platform API - Add an "AI Endpoints" section to the Platform API tab with the Chat API (POST /chat/stream-chat-state), extracted from the ai-engineer OpenAPI spec into api-reference/chat.yaml via scripts/extract-chat.js. - Document Bearer auth on the REST and SCIM APIs in authentication.mdx. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(api): add Core Data endpoints, restructure API tab, hide internal routes Build out the API docs tab into three families — Core Data, AI, and Platform — and trim it to the curated public surface. - Core Data API: extract POST /v1/load and GET /v1/meta from the in-repo cubejs-api-gateway/openspec.yml into api-reference/core-data.yaml via scripts/extract-core-data.js, with the deployment data-API host (cubecloudapp.dev, region + deployment) and Api-Key/JWT auth. Rename /v1/load to "JSON query" and hand-author the "SQL query" endpoint (POST /v1/cubesql), including an enum + default for the cache parameter. - Reorder the API tab: Getting Started, Core Data Endpoints, AI Endpoints, Platform Endpoints. Flatten single-endpoint groups; rename the tab to "API"; rename SCIM groups to Users/Groups; drop the Changelog group for now. - Hide internal/incomplete Platform routes (Groups, User Groups, Agents, Metadata, Users, User Attributes, Resource Policies, App Theme, AI Engineer) from docs.json and api.yaml, and add an EXCLUDE_OPERATIONS list to scripts/extract-api.mjs so a re-pull won't resurface them. - Introduction: add a three-API overview with per-family auth, move Available endpoints (now covering all three APIs, with per-API base URLs) ahead of the client-library sections, and document both the Core Data (@cubejs-client/core) and Platform (@cube-dev/platform-client) client libraries. - Authentication: document Bearer on REST/SCIM and repoint the SCIM base-URL link to #platform-api. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(api): consolidate client libraries section, broaden intro description - Merge the Core Data and Platform client-library sections under a single "Client libraries" heading with one subsection each. - Update the Introduction description to cover all three API families (Core Data, AI, Platform) instead of the Platform/SCIM-only framing. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 281e920 commit 68e9e88

9 files changed

Lines changed: 1769 additions & 441 deletions

File tree

‎docs-mintlify/api-reference/api.yaml‎

Lines changed: 0 additions & 309 deletions
Original file line numberDiff line numberDiff line change
@@ -23,68 +23,9 @@ tags:
2323
- name: Workbooks
2424
- name: Notifications
2525
- name: Workspace
26-
- name: Agents
27-
- name: Metadata
28-
- name: Users
29-
- name: Groups
30-
- name: User Groups
31-
- name: User Attributes
32-
- name: Resource Policies
33-
- name: App Theme
34-
- name: AI Engineer
3526
- name: Embed
3627
- name: Embed Tenants
3728
paths:
38-
/v1/ai-engineer/active-region:
39-
get:
40-
operationId: getMyActiveAgentRegion
41-
responses:
42-
'200':
43-
content:
44-
application/json:
45-
schema:
46-
$ref: '#/components/schemas/ActiveAgentRegion'
47-
description: ''
48-
summary: Get my active agent region
49-
tags:
50-
- AI Engineer
51-
/v1/ai-engineer/settings:
52-
get:
53-
operationId: getAIEngineerSettings
54-
parameters:
55-
- in: query
56-
name: deploymentId
57-
required: false
58-
schema:
59-
type: number
60-
- in: query
61-
name: agentId
62-
required: false
63-
schema:
64-
type: number
65-
responses:
66-
'200':
67-
content:
68-
application/json:
69-
schema:
70-
$ref: '#/components/schemas/AIEngineerSettings'
71-
description: ''
72-
summary: Get ai engineer settings
73-
tags:
74-
- AI Engineer
75-
/v1/app-theme:
76-
get:
77-
operationId: getAppTheme
78-
responses:
79-
'200':
80-
content:
81-
application/json:
82-
schema:
83-
$ref: '#/components/schemas/AppThemeResponse'
84-
description: ''
85-
summary: Get app theme
86-
tags:
87-
- App Theme
8829
/v1/deployments:
8930
get:
9031
operationId: getDeployments
@@ -173,64 +114,6 @@ paths:
173114
summary: Get deployment
174115
tags:
175116
- Deployments
176-
/v1/deployments/{deploymentId}/agent-skills:
177-
get:
178-
operationId: getAgentSkills
179-
parameters:
180-
- in: path
181-
name: deploymentId
182-
required: true
183-
schema:
184-
type: number
185-
- in: query
186-
name: space
187-
schema:
188-
oneOf:
189-
- type: string
190-
- type: 'null'
191-
- in: query
192-
name: branchName
193-
schema:
194-
oneOf:
195-
- type: string
196-
- type: 'null'
197-
responses:
198-
'200':
199-
content:
200-
application/json:
201-
schema:
202-
$ref: '#/components/schemas/AgentSkillsResponse'
203-
description: ''
204-
summary: Get agent skills
205-
tags:
206-
- Agents
207-
/v1/deployments/{deploymentId}/agents:
208-
get:
209-
operationId: getAgents
210-
parameters:
211-
- in: path
212-
name: deploymentId
213-
required: true
214-
schema:
215-
type: number
216-
- in: query
217-
name: allowEmbedding
218-
schema:
219-
oneOf:
220-
- type: boolean
221-
- type: 'null'
222-
responses:
223-
'200':
224-
content:
225-
application/json:
226-
schema:
227-
items:
228-
$ref: '#/components/schemas/Agent'
229-
type: array
230-
description: ''
231-
summary: Get agents
232-
tags:
233-
- Agents
234117
/v1/deployments/{deploymentId}/environments:
235118
get:
236119
operationId: getDeploymentEnvironments
@@ -1851,198 +1734,6 @@ paths:
18511734
summary: Exchange a session for an embed token
18521735
tags:
18531736
- Embed
1854-
/v1/groups/{id}:
1855-
delete:
1856-
operationId: deleteGroup
1857-
parameters:
1858-
- in: path
1859-
name: id
1860-
required: true
1861-
schema:
1862-
type: number
1863-
responses:
1864-
'200':
1865-
content:
1866-
application/json: {}
1867-
description: Successful response
1868-
summary: Delete group
1869-
tags:
1870-
- Groups
1871-
/v1/meta:
1872-
post:
1873-
operationId: getMetadata
1874-
requestBody:
1875-
content:
1876-
application/json:
1877-
schema:
1878-
$ref: '#/components/schemas/MetadataRequest'
1879-
description: MetadataRequest
1880-
required: false
1881-
responses:
1882-
'200':
1883-
content:
1884-
application/json: {}
1885-
description: Successful response
1886-
summary: Get metadata
1887-
tags:
1888-
- Metadata
1889-
/v1/resource-policies:
1890-
get:
1891-
operationId: getPolicies
1892-
parameters:
1893-
- in: query
1894-
name: resourceType
1895-
required: true
1896-
schema:
1897-
$ref: '#/components/schemas/GetResourcePoliciesQueryResourceType'
1898-
- in: query
1899-
name: resourceId
1900-
required: true
1901-
schema:
1902-
type: integer
1903-
responses:
1904-
'200':
1905-
content:
1906-
application/json:
1907-
schema:
1908-
$ref: '#/components/schemas/ResourcePoliciesResponse'
1909-
description: ''
1910-
summary: Get policies
1911-
tags:
1912-
- Resource Policies
1913-
/v1/resource-policies/group:
1914-
put:
1915-
operationId: updateGroupPolicy
1916-
requestBody:
1917-
content:
1918-
application/json:
1919-
schema:
1920-
$ref: '#/components/schemas/UpdateResourceGroupPolicyBody'
1921-
description: UpdateResourceGroupPolicyBody
1922-
required: false
1923-
responses:
1924-
'200':
1925-
content:
1926-
application/json: {}
1927-
description: Successful response
1928-
summary: Update group policy
1929-
tags:
1930-
- Resource Policies
1931-
/v1/resource-policies/user:
1932-
put:
1933-
operationId: updateUserPolicy
1934-
requestBody:
1935-
content:
1936-
application/json:
1937-
schema:
1938-
$ref: '#/components/schemas/UpdateResourceUserPolicyBody'
1939-
description: UpdateResourceUserPolicyBody
1940-
required: false
1941-
responses:
1942-
'200':
1943-
content:
1944-
application/json: {}
1945-
description: Successful response
1946-
summary: Update user policy
1947-
tags:
1948-
- Resource Policies
1949-
/v1/user-attributes/{id}:
1950-
delete:
1951-
operationId: deleteUserAttribute
1952-
parameters:
1953-
- in: path
1954-
name: id
1955-
required: true
1956-
schema:
1957-
type: number
1958-
responses:
1959-
'200':
1960-
content:
1961-
application/json: {}
1962-
description: Successful response
1963-
summary: Delete user attribute
1964-
tags:
1965-
- User Attributes
1966-
/v1/user-groups:
1967-
get:
1968-
operationId: listGroups
1969-
parameters:
1970-
- in: query
1971-
name: after
1972-
schema:
1973-
oneOf:
1974-
- type: string
1975-
- type: 'null'
1976-
- in: query
1977-
name: first
1978-
schema:
1979-
oneOf:
1980-
- minimum: 1
1981-
type: integer
1982-
- type: 'null'
1983-
responses:
1984-
'200':
1985-
content:
1986-
application/json:
1987-
schema:
1988-
$ref: '#/components/schemas/UserGroupsConnectionResponse'
1989-
description: ''
1990-
summary: List groups
1991-
tags:
1992-
- User Groups
1993-
/v1/users:
1994-
get:
1995-
operationId: getUsers
1996-
parameters:
1997-
- in: query
1998-
name: after
1999-
schema:
2000-
oneOf:
2001-
- type: string
2002-
- type: 'null'
2003-
- in: query
2004-
name: first
2005-
schema:
2006-
oneOf:
2007-
- minimum: 1
2008-
type: integer
2009-
- type: 'null'
2010-
responses:
2011-
'200':
2012-
content:
2013-
application/json:
2014-
schema:
2015-
$ref: '#/components/schemas/UsersConnection'
2016-
description: ''
2017-
summary: Get users
2018-
tags:
2019-
- Users
2020-
/v1/users/embed-theme:
2021-
get:
2022-
operationId: getEmbedTheme
2023-
responses:
2024-
'200':
2025-
content:
2026-
application/json:
2027-
schema:
2028-
$ref: '#/components/schemas/EmbedTheme'
2029-
description: ''
2030-
summary: Get embed theme
2031-
tags:
2032-
- Users
2033-
/v1/users/me:
2034-
get:
2035-
operationId: getMe
2036-
responses:
2037-
'200':
2038-
content:
2039-
application/json:
2040-
schema:
2041-
$ref: '#/components/schemas/User'
2042-
description: ''
2043-
summary: Get me
2044-
tags:
2045-
- Users
20461737
components:
20471738
securitySchemes:
20481739
apiKey:

‎docs-mintlify/api-reference/authentication.mdx‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,21 @@ curl --request GET \
2424
--header 'Authorization: Api-Key <YOUR_API_KEY>'
2525
```
2626

27+
The REST API also accepts a `Bearer` prefix for OAuth access tokens, for
28+
integrations built on Cube Cloud's OAuth flow:
29+
30+
```text
31+
Authorization: Bearer <YOUR_OAUTH_ACCESS_TOKEN>
32+
```
33+
34+
<Note>
35+
36+
`Bearer` here authenticates an **OAuth access token**, not your API key — the two
37+
are validated differently. Send API keys with the `Api-Key` prefix; a Cube Cloud
38+
API key sent as `Bearer` will be rejected. (SCIM is the exception — see below.)
39+
40+
</Note>
41+
2742
## SCIM API (`/api/scim/v2`)
2843

2944
Authenticate user and group provisioning requests with a SCIM bearer token,
@@ -33,9 +48,14 @@ configured in your identity provider's SCIM integration:
3348
Authorization: Bearer <YOUR_SCIM_TOKEN>
3449
```
3550

51+
The SCIM API requires the `Bearer` prefix because identity providers (Microsoft
52+
Entra ID, Okta, and others) send credentials this way per
53+
[RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644). The SCIM token is a
54+
Cube Cloud API key, so `Api-Key <YOUR_SCIM_TOKEN>` is also accepted here.
55+
3656
Generate a SCIM token in your Cube Cloud account settings, then configure it in
3757
your identity provider alongside the
38-
[base URL](/api-reference/introduction#base-url).
58+
[base URL](/api-reference/introduction#platform-api).
3959

4060
```bash
4161
curl --request GET \

0 commit comments

Comments
 (0)