docs(api-reference): update GET /api/chats response shape by arpitgupta1214 · Pull Request #227 · recoupable/docs

arpitgupta1214 · 2026-05-29T15:24:10Z

Updates the openapi spec for GET /api/chats. The response now carries id, title, accountId, sessionId, and updatedAt per row; the ChatRoom schema is modified in place rather than introducing a parallel one.

ChatRoom becomes { id, title, accountId, sessionId, updatedAt } (camelCase, all required).
GET /api/chats operation description, sessionId field, and artist_account_id parameter use product-facing language.
artist_account_id stays a first-class filter; description notes the parameter is currently inert.

POST /api/chats and PATCH /api/chats/{id} still reference ChatRoom and will be misaligned with their actual response shape until they're removed in a follow-up cleanup PR.

Test plan

Mintlify preview renders the updated GET /api/chats page with the new fields and copy.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-05-29T15:24:21Z

Warning

Review limit reached

@sweetmantech, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 23 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 66cdfaa0-8c13-49b8-9ee7-869c9e989c15

📥 Commits

Reviewing files that changed from the base of the PR and between c76b6b2 and 23a32eb.

📒 Files selected for processing (1)

api-reference/openapi/research.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/get-chats-session-scoped

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cubic-dev-ai

No issues found across 1 file

_{Re-trigger cubic}

…i/chats The artist filter is staying — it's just dormant until sessions.artist_id is backfilled. Drop the deprecated marker and reword the description so clients know the parameter is a normal first-class filter that will start matching rows once the database column lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cubic-dev-ai

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/research.json">

<violation number="1" location="api-reference/openapi/research.json:24">
P2: Remove the `deprecated: true` flag from `artist_account_id` while documenting that the parameter currently has no effect. Consumers seeing a non-deprecated, non-functional parameter will try using it, get empty results, and have no indication that the behavior is expected. Either restore `deprecated: true` to signal the parameter should not be relied on, or remove it from the spec entirely until it actually filters.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai · 2026-05-29T16:09:29Z

+            "description": "Optional. Filter chats to only include those for the specified artist. The filter is wired through but currently has no effect — `sessions.artist_id` is not yet populated, so no rows match. Will start filtering once the artist column is backfilled onto sessions.",
            "required": false,
            "schema": {
              "type": "string",


P2: Remove the deprecated: true flag from artist_account_id while documenting that the parameter currently has no effect. Consumers seeing a non-deprecated, non-functional parameter will try using it, get empty results, and have no indication that the behavior is expected. Either restore deprecated: true to signal the parameter should not be relied on, or remove it from the spec entirely until it actually filters.

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>Remove the `deprecated: true` flag from `artist_account_id` while documenting that the parameter currently has no effect. Consumers seeing a non-deprecated, non-functional parameter will try using it, get empty results, and have no indication that the behavior is expected. Either restore `deprecated: true` to signal the parameter should not be relied on, or remove it from the spec entirely until it actually filters.</comment> <file context> @@ -21,9 +21,8 @@ "name": "artist_account_id", "in": "query", - "description": "Reserved for the artist-surface migration. Currently accepted but does not filter — the new session-scoped listing does not yet carry artist linkage. Will return once `sessions.artist_id` is backfilled.", + "description": "Optional. Filter chats to only include those for the specified artist. The filter is wired through but currently has no effect — `sessions.artist_id` is not yet populated, so no rows match. Will start filtering once the artist column is backfilled onto sessions.", "required": false, - "deprecated": true, </file context>

…ed GET Replace ChatRoom's rooms-shape fields (account_id, topic, updated_at, artist_id) with the session-scoped wire shape (id, title, accountId, sessionId, updatedAt) and drop the parallel SessionScopedChat schema. ChatRoom is also referenced by CreateChatResponse and UpdateChatResponse (POST /api/chats, PATCH /api/chats/{id}), which still return the rooms shape until they're deleted in a follow-up cleanup PR. Those operation docs are knowingly stale for that brief window. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ions The public spec shouldn't lean on internal migration language — "session-scoped", "joined to parent sessions", "sessions.artist_id". External consumers care about what the fields are and how to use them, not the internal join shape or the schema column they came from. Reword the operation description, the artist_account_id parameter note, and a couple of field descriptions to focus on what each thing is and how to use it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pairs with the projection that api#626 will add (`session.artist_id` → `artistId` per row in GET /api/chats), so the docs describe the field the client will receive. Nullable per the underlying column (`sessions.artist_id` is nullable, populated for sessions whose room had an artist or whose creator passed `artistId` to `POST /api/sessions`). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Drops the "currently has no effect" caveat. Documentation-driven: the docs describe the contract api#626 will satisfy (filter by `session.artist_id`) rather than papering over the temporary no-op.

cubic-dev-ai

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/research.json">

<violation number="1" location="api-reference/openapi/research.json:24">
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.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai · 2026-05-31T02:40:44Z

            "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.",


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."

docs(api-reference): update GET /api/chats to session-scoped shape

ac5cd06

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

arpitgupta1214 requested a review from sweetmantech as a code owner May 29, 2026 15:24

cubic-dev-ai Bot reviewed May 29, 2026

View reviewed changes

arpitgupta1214 force-pushed the docs/get-chats-session-scoped branch from 2a407d2 to 31b5ea3 Compare May 29, 2026 16:00

cubic-dev-ai Bot reviewed May 29, 2026

View reviewed changes

arpitgupta1214 force-pushed the docs/get-chats-session-scoped branch from f6a70e1 to b4a3dcb Compare May 29, 2026 20:38

arpitgupta1214 changed the title ~~docs(api-reference): update GET /api/chats to session-scoped shape~~ docs(api-reference): update GET /api/chats response shape May 29, 2026

sweetmantech and others added 3 commits May 30, 2026 21:34

Merge branch 'main' into docs/get-chats-session-scoped

c7b8c24

docs(chats): describe artist_account_id as a real filter

23a32eb

Drops the "currently has no effect" caveat. Documentation-driven: the docs describe the contract api#626 will satisfy (filter by `session.artist_id`) rather than papering over the temporary no-op.

sweetmantech approved these changes May 31, 2026

View reviewed changes

cubic-dev-ai Bot reviewed May 31, 2026

View reviewed changes

sweetmantech merged commit b10eef7 into main May 31, 2026
3 checks passed

This was referenced May 31, 2026

Post-cutover plan: chat.recoupable.com → /api/chat/workflow recoupable/chat#1747

Closed

feat(chat): consume session-scoped chat listing in sidebar recoupable/chat#1756

Merged

Promote chat-workflow cutover stack to main recoupable/api#631

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

docs(api-reference): update GET /api/chats response shape#227
sweetmantech merged 7 commits into
mainfrom
docs/get-chats-session-scoped

arpitgupta1214 commented May 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 29, 2026 •

edited

Loading

Review limit reached

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot May 29, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot May 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	"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."

Conversation

arpitgupta1214 commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Uh oh!

coderabbitai Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

arpitgupta1214 commented May 29, 2026 •

edited

Loading

coderabbitai Bot commented May 29, 2026 •

edited

Loading