Skip to content

docs(api-reference): update GET /api/chats response shape #227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 7 commits into from
May 31, 2026
Merged

docs(api-reference): update GET /api/chats response shape #227

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ac5cd06
docs(api-reference): update GET /api/chats to session-scoped shape
arpitgupta1214 May 29, 2026
31b5ea3
docs(api-reference): keep artist_account_id non-deprecated on GET /ap…
arpitgupta1214 May 29, 2026
b4a3dcb
docs(api-reference): modify ChatRoom schema in place for session-scop…
arpitgupta1214 May 29, 2026
f77477c
docs(api-reference): drop internal vocab from GET /api/chats descript…
arpitgupta1214 May 29, 2026
c7b8c24
Merge branch 'main' into docs/get-chats-session-scoped
sweetmantech May 31, 2026
e710dd4
docs(chats): add artistId to ChatRoom response schema
sweetmantech May 31, 2026
23a32eb
docs(chats): describe artist_account_id as a real filter
sweetmantech May 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 24 additions & 14 deletions api-reference/openapi/research.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@
"paths": {
"/api/chats": {
"get": {
"description": "Retrieve chat rooms (conversations) for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Optionally filter by an artist_account_id. The endpoint returns metadata about each room, including the topic, associated artist, and last updated timestamp.",
"description": "Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.",
"parameters": [
{
"name": "artist_account_id",
"in": "query",
"description": "Optional. Filter chats to only include those for the specified artist.",
"description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. Combine with `account_id` to scope by both owner and artist.",

@cubic-dev-ai cubic-dev-ai Bot May 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: The artist_account_id parameter description was changed to describe active filtering behavior, but the PR description states the parameter is currently inert. If the parameter is still inert, this description will mislead API consumers into believing the filter works when it has no effect. Either restore the currently has no effect caveat (or add a similar accepted but currently has no effect note) to match the stated intent, or update the PR description to reflect that filtering is now active.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/research.json, line 24:

<comment>The `artist_account_id` parameter description was changed to describe active filtering behavior, but the PR description states the parameter is currently inert. If the parameter is still inert, this description will mislead API consumers into believing the filter works when it has no effect. Either restore the `currently has no effect` caveat (or add a similar `accepted but currently has no effect` note) to match the stated intent, or update the PR description to reflect that filtering is now active.</comment>

<file context>
@@ -21,7 +21,7 @@
             "name": "artist_account_id",
             "in": "query",
-            "description": "Optional. Filter chats to only include those for the specified artist. The parameter is accepted but currently has no effect; artist filtering returns in a future release.",
+            "description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. Combine with `account_id` to scope by both owner and artist.",
             "required": false,
             "schema": {
</file context>
Suggested change
"description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. Combine with `account_id` to scope by both owner and artist.",
"description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. The parameter is accepted but currently has no effect; artist filtering returns in a future release."

"required": false,
"schema": {
"type": "string",
Expand Down Expand Up @@ -3236,33 +3236,43 @@
},
"ChatRoom": {
"type": "object",
"required": [
"id",
"title",
"accountId",
"sessionId",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the chat room"
"description": "Chat id."
},
"account_id": {
"title": {
"type": "string",
"description": "Display title for the chat."
},
"accountId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "UUID of the associated account (can be null if not set)"
"description": "Owning account for this chat."
},
"topic": {
"sessionId": {
"type": "string",
"nullable": true,
"description": "Optional topic or description of the room (null if not provided)"
"format": "uuid",
"description": "Session that owns this chat. Combine with `id` to build the chat URL: `/sessions/{sessionId}/chats/{id}`."
},
"updated_at": {
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO timestamp of the last update to the room"
"description": "ISO timestamp of the last update."
},
"artist_id": {
"artistId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "UUID of the associated artist account (null when not applicable)"
"description": "Artist account id this chat's session was created in the context of, or `null` when no artist was associated. Inherited from `sessions.artist_id` on the owning session."
}
}
},
Expand Down Expand Up @@ -3844,7 +3854,7 @@
"items": {
"$ref": "#/components/schemas/ChatRoom"
},
"description": "Array of chat room objects"
"description": "Array of chat objects"
}
}
},
Expand Down