fix: harden research API response schemas and add error responses#101
fix: harden research API response schemas and add error responses#101sidneyswift wants to merge 6 commits intomainfrom
Conversation
- Fix ResearchCareerResponse: rename `data` → `career` to match handler - Fix ResearchWebResponse: rename `content` → `snippet`, add `date` and `last_updated` fields to match Perplexity search results - Fix ResearchEnrichResponse: flatten `research_basis.citations` → top-level `citations` to match handler output - Fix ResearchPeopleResult: add missing `id`, `publishedDate`, `author` fields from Exa search results - Add `example: "success"` to all response schema `status` fields - Create reusable `ResearchErrorResponse` component schema - Add 400 (validation) and 401 (auth) error responses to all 30 research endpoints referencing ResearchErrorResponse via $ref Made-with: Cursor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughUpdated the OpenAPI spec to standardize 400/401 error responses for /api/research/* with a new ResearchErrorResponse, tightened and renamed multiple Research* response/request schemas (field renames, nesting, required/nullable additions, examples), adjusted /api/research/charts query params, and small CLI doc text updates for research commands. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api-reference/openapi.json (1)
7144-7165:⚠️ Potential issue | 🟡 MinorKeep the endpoint prose aligned with the declared schema fields.
Line 7144 says the profile response includes social URLs and career stage, but
ResearchProfileResponsedoes not declare those fields. Line 7390 similarly promises popularity and platform IDs thatResearchTrackResponsedoes not expose. Either add the fields explicitly or trim the descriptions;additionalProperties: truewill not make them discoverable in Mintlify or generated clients.Also applies to: 7390-7411, 15712-15758, 15909-15938
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 7144 - 7165, Endpoint descriptions claim fields (e.g., social URLs, career stage, popularity, platform IDs) that are not declared on the corresponding response schemas; update the OpenAPI spec so the prose matches the schemas by either (A) adding the missing properties to the referenced schemas (e.g., ResearchProfileResponse, ResearchTrackResponse) with proper types and descriptions, or (B) removing/trimming those claims from the endpoint descriptions; do not rely on additionalProperties: true to communicate these fields, and ensure any added properties are documented in the schema so generated clients and Mintlify can discover them.
🧹 Nitpick comments (1)
api-reference/openapi.json (1)
14939-14948: Verify whether the research 200 schemas are now success-only.Line 14942 still permits
status: "error", while Lines 14962, 15218, and 16069 no longer constrain the field beyondstring. If the newResearchErrorResponseis meant to cover the remaining error paths, these 200 schemas can be tightened toenum: ["success"]; otherwise the 200-error variant should be modeled explicitly instead of leaving the contract inconsistent across endpoints.Possible tightening if 200 responses are success-only
"status": { "type": "string", - "enum": [ - "success", - "error" - ], + "enum": [ + "success" + ], "example": "success" },Please confirm this against the live-response validation step before applying it across all research success schemas.
Also applies to: 14958-14965, 15109-15120, 15215-15220, 16065-16071
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14939 - 14948, Confirm whether 200 responses for research endpoints are intended to be success-only; if so, tighten the ResearchAlbumsResponse and sibling 200-level response schemas (e.g., the Research*Response objects referenced around ResearchAlbumsResponse) by changing their "status" enum to ["success"] (apply same change to the other occurrences you noted), otherwise add an explicit 200-level error variant instead of leaving "status" as an unconstrained string; verify the decision against the live-response validation step before applying the change and ensure consistency with the ResearchErrorResponse model used for non-200 error paths.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@api-reference/openapi.json`:
- Around line 7144-7165: Endpoint descriptions claim fields (e.g., social URLs,
career stage, popularity, platform IDs) that are not declared on the
corresponding response schemas; update the OpenAPI spec so the prose matches the
schemas by either (A) adding the missing properties to the referenced schemas
(e.g., ResearchProfileResponse, ResearchTrackResponse) with proper types and
descriptions, or (B) removing/trimming those claims from the endpoint
descriptions; do not rely on additionalProperties: true to communicate these
fields, and ensure any added properties are documented in the schema so
generated clients and Mintlify can discover them.
---
Nitpick comments:
In `@api-reference/openapi.json`:
- Around line 14939-14948: Confirm whether 200 responses for research endpoints
are intended to be success-only; if so, tighten the ResearchAlbumsResponse and
sibling 200-level response schemas (e.g., the Research*Response objects
referenced around ResearchAlbumsResponse) by changing their "status" enum to
["success"] (apply same change to the other occurrences you noted), otherwise
add an explicit 200-level error variant instead of leaving "status" as an
unconstrained string; verify the decision against the live-response validation
step before applying the change and ensure consistency with the
ResearchErrorResponse model used for non-200 error paths.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6fbea925-cd8b-4724-bb3f-f6f6e2f21bb3
📒 Files selected for processing (1)
api-reference/openapi.json
- Instagram posts: rename `posts` to `top_posts` + `top_reels` - Lookup: wrap ID fields inside `data` object to match handler - Audience: replace simplified `age`/`gender`/`countries` with actual Chartmetric fields (`audience_genders`, `audience_genders_per_age`, `top_countries`, `top_cities`, `audience_brand_affinities`) - Extract: make `errors` field optional (only present on partial failure) - Charts: document default values for country (US), interval (daily), type (regional), and latest (true) params - Enrich: note that `schema.type: "object"` is required Made-with: Cursor
Schema Verification ResultsAll 30 research endpoint response schemas have been verified against live API responses on the preview deployment. Fixes applied in this PR
VerificationAll 30 endpoints tested with cURL against the API preview — see api#366 comment for full results. |
Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api-reference/openapi.json (1)
6196-6200:⚠️ Potential issue | 🟠 Major
latestquery param type conflicts with its documented semanticsLine [6196] documents a boolean flag, but Lines [6198-6199] define it as a string with
"default": "true". This creates contract ambiguity for generated clients.🛠️ Proposed parameter schema fix
"latest": { "in": "query", "required": false, "description": "Return only the latest chart. Defaults to `true`.", "schema": { - "type": "string", - "default": "true" + "type": "boolean", + "default": true } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 6196 - 6200, The OpenAPI parameter "latest" currently has a schema with "type": "string" and "default": "true", which conflicts with its boolean semantics; update the "latest" parameter's schema to use "type": "boolean" and set "default": true (a boolean, not a string) so generated clients receive the correct contract for the "latest" query param.
🧹 Nitpick comments (1)
api-reference/openapi.json (1)
14965-14968: Consider constraining successstatusfields to a fixed enum/constThese success-response schemas now use
type: "string"withexample: "success". For stricter contracts, preferenum: ["success"](orconst: "success"), especially since this PR is hardening API schemas.Also applies to: 15016-15019, 15240-15243, 16124-16127
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14965 - 14968, Replace the loose "status" property schemas that are currently "type": "string" with a fixed value (use either "const": "success" or "enum": ["success"]) in each response schema where "status" is always "success" (the "status" property definitions in the response schema objects shown in the diff and the other occurrences noted). Update the example if necessary to match the chosen const/enum and keep the schema consistent across the other occurrences mentioned.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 6489-6490: The OpenAPI contract doesn't enforce the documented
requirement that ResearchEnrichRequest.schema must be an object; update the
OpenAPI schema for ResearchEnrichRequest (the property named "schema" on
ResearchEnrichRequest) to require a top-level "type": "object" (or an equivalent
"const" constraint) so generated validators/SDKs reject non-object
schemas—modify the ResearchEnrichRequest.schema definition where
components/schemas define it (the entries labeled ResearchEnrichRequest and its
"schema" property) to include "type": "object" and, if applicable, add
"required": ["schema"]/explicit validation keywords to ensure the constraint is
enforced.
---
Outside diff comments:
In `@api-reference/openapi.json`:
- Around line 6196-6200: The OpenAPI parameter "latest" currently has a schema
with "type": "string" and "default": "true", which conflicts with its boolean
semantics; update the "latest" parameter's schema to use "type": "boolean" and
set "default": true (a boolean, not a string) so generated clients receive the
correct contract for the "latest" query param.
---
Nitpick comments:
In `@api-reference/openapi.json`:
- Around line 14965-14968: Replace the loose "status" property schemas that are
currently "type": "string" with a fixed value (use either "const": "success" or
"enum": ["success"]) in each response schema where "status" is always "success"
(the "status" property definitions in the response schema objects shown in the
diff and the other occurrences noted). Update the example if necessary to match
the chosen const/enum and keep the schema consistent across the other
occurrences mentioned.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d92d3c9d-aed5-40ac-8715-3900782c23eb
📒 Files selected for processing (2)
api-reference/openapi.jsoncli.mdx
…stic Made-with: Cursor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
cli.mdx (1)
350-355:⚠️ Potential issue | 🟡 MinorGeneralize the description to match the examples without artist argument.
Line 350 says "playing an artist's music" (implying artist-scoped behavior), but the examples on lines 353-354 show no artist argument, and the command is not listed among the artist-scoped commands documented in the file. Either clarify that the command works without an artist parameter (e.g., "List popular radio stations") or add artist argument examples if it supports filtering by artist.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 350 - 355, The description "playing an artist's music" is inconsistent with the examples for the CLI command recoup research radio; either generalize the sentence to match the examples (e.g., change the short description to "List radio stations" or "List popular radio stations") or, if the command supports an artist filter, add example usages showing the artist argument (e.g., recoup research radio "<artist name>" and recoup research radio "<artist name>" --json). Update the CLI doc string that references the command name recoup research radio accordingly so the description and examples are aligned.
🧹 Nitpick comments (1)
cli.mdx (1)
379-381: Trim repetitive phrasing in the deep section title/lead.“Deep web research” is repeated in both the heading and sentence; this can be tighter for scanability.
✂️ Suggested wording
-### Deep web research - -Deep web research that synthesizes information from across the web into a cited report. +### Deep research + +Synthesize information from across the web into a cited report.As per coding guidelines, "Keep documentation content concise and scannable" and "Use clear, self-documenting titles and descriptions in documentation."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 379 - 381, The heading "### Deep web research" and the lead sentence repeat the phrase; update either the heading or the sentence to remove duplication for conciseness — e.g., keep the heading "### Deep web research" and change the lead to a tighter description like "Synthesizes information from across the web into a cited report" or change the heading to "### Deep research" and keep the original lead; apply this edit to the "### Deep web research" heading and its following lead sentence to improve scanability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@cli.mdx`:
- Around line 350-355: The description "playing an artist's music" is
inconsistent with the examples for the CLI command recoup research radio; either
generalize the sentence to match the examples (e.g., change the short
description to "List radio stations" or "List popular radio stations") or, if
the command supports an artist filter, add example usages showing the artist
argument (e.g., recoup research radio "<artist name>" and recoup research radio
"<artist name>" --json). Update the CLI doc string that references the command
name recoup research radio accordingly so the description and examples are
aligned.
---
Nitpick comments:
In `@cli.mdx`:
- Around line 379-381: The heading "### Deep web research" and the lead sentence
repeat the phrase; update either the heading or the sentence to remove
duplication for conciseness — e.g., keep the heading "### Deep web research" and
change the lead to a tighter description like "Synthesizes information from
across the web into a cited report" or change the heading to "### Deep research"
and keep the original lead; apply this edit to the "### Deep web research"
heading and its following lead sentence to improve scanability.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
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="cli.mdx">
<violation number="1" location="cli.mdx:350">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
This description claims the endpoint lists radio stations "playing an artist's music," but the OpenAPI spec explicitly marks this endpoint as **NOT artist-scoped** and the CLI example takes no artist argument. Revert to something accurate like the original or the spec's own description: "List radio stations tracked by Chartmetric."</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
…, enrich schema Made-with: Cursor
Addressing review comments1. Profile/metrics descriptions promise fields not in schema (CodeRabbit, minor) 2. 3. Enrich schema doesn't enforce 4. Radio description inaccurate (Cubic, P1) All fixes in commit |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
api-reference/openapi.json (2)
5967-5986: Consider using reusable response components for repeated 400/401 blocksThe same
400/401response objects are repeated across all research operations. Centralizing them undercomponents.responseswill reduce duplication and prevent drift.♻️ Example refactor pattern
+ "components": { + "responses": { + "ResearchValidationError": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "ResearchAuthError": { + "description": "Authentication failed — invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + } + } + }- "400": { ...ResearchErrorResponse... }, - "401": { ...ResearchErrorResponse... } + "400": { "$ref": "#/components/responses/ResearchValidationError" }, + "401": { "$ref": "#/components/responses/ResearchAuthError" }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5967 - 5986, The OpenAPI spec repeats identical 400 and 401 response objects for research endpoints; refactor by creating reusable entries under components.responses (e.g., components.responses.ResearchBadRequest and components.responses.Unauthorized or similar) that reference the existing ResearchErrorResponse schema and then replace each inline "400" and "401" response block with $ref pointers to those new components; update any operation objects that currently embed the repeated blocks to use these component refs to remove duplication and keep semantics identical.
14965-14968: Keepstatusconstrained in success response schemasIn several updated schemas,
statusbecame an unconstrained string with only an example. That loosens the contract and reduces SDK type safety. Preferenum: ["success"](orconst: "success") for 200-success payloads.✅ Example for one affected schema
"status": { - "type": "string", - "example": "success" + "type": "string", + "enum": ["success"], + "example": "success" }Also applies to: 15016-15019, 15258-15261, 15476-15478, 15531-15533, 16142-16145
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14965 - 14968, The response schema currently defines "status" as an unconstrained string with only an example; update each affected success-response schema (e.g., the schema object that contains the "status" property shown in this diff and the other listed occurrences) to constrain it to the literal "success" by replacing the loose string type with either "enum": ["success"] or "const": "success" so the OpenAPI contract and generated SDK types reflect the fixed success value. Locate the "status" property definitions in the shown schema and the other occurrences (lines referenced in the comment) and change their definition accordingly, keeping any existing example if desired.cli.mdx (2)
379-381: Tighten repetitive “Deep web research” phrasing.The heading and first sentence repeat the same wording; a shorter sentence improves scanability.
✏️ Suggested copy tweak
### Deep web research -Deep web research that synthesizes information from across the web into a cited report. +Synthesize web findings into a cited report.As per coding guidelines, "Keep documentation content concise and scannable."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 379 - 381, The heading "Deep web research" and the following sentence repeat the same phrase; remove the redundancy by shortening the sentence under the "Deep web research" heading to a concise descriptor (e.g., "Synthesizes information from across the web into a cited report.") so the heading remains and the body becomes a single scannable line; update the sentence text beneath the "Deep web research" heading to the concise version and remove the original repetitive sentence.
350-350: Consider making radio scope explicit.“List tracked radio stations” is fine, but “List globally tracked radio stations” is slightly clearer at a glance.
As per coding guidelines, "Use clear, self-documenting titles and descriptions in documentation."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` at line 350, Update the documentation string "List tracked radio stations" to explicitly indicate scope by changing it to "List globally tracked radio stations" wherever the exact phrase appears (e.g., the title or description in the CLI docs entry that currently reads "List tracked radio stations") so the command description is self-documenting and unambiguous; ensure the modified phrase is used consistently in the CLI help/MDX entry and keep formatting identical to surrounding lines.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 6166-6190: The schemas for the query parameters "country",
"interval", and "type" lack the constraints described in their descriptions;
update the parameter schemas in openapi.json for the "country" parameter to
enforce a two-letter ISO code (e.g., add minLength: 2, maxLength: 2 and a
pattern like two alphabetic chars) and update "interval" and "type" to use
explicit enums (interval: ["daily","weekly"]; type: ["regional","viral"]) so
generated validators/SDKs will enforce the documented constraints; locate the
parameter objects named "country", "interval", and "type" and add these schema
constraint fields accordingly.
---
Nitpick comments:
In `@api-reference/openapi.json`:
- Around line 5967-5986: The OpenAPI spec repeats identical 400 and 401 response
objects for research endpoints; refactor by creating reusable entries under
components.responses (e.g., components.responses.ResearchBadRequest and
components.responses.Unauthorized or similar) that reference the existing
ResearchErrorResponse schema and then replace each inline "400" and "401"
response block with $ref pointers to those new components; update any operation
objects that currently embed the repeated blocks to use these component refs to
remove duplication and keep semantics identical.
- Around line 14965-14968: The response schema currently defines "status" as an
unconstrained string with only an example; update each affected success-response
schema (e.g., the schema object that contains the "status" property shown in
this diff and the other listed occurrences) to constrain it to the literal
"success" by replacing the loose string type with either "enum": ["success"] or
"const": "success" so the OpenAPI contract and generated SDK types reflect the
fixed success value. Locate the "status" property definitions in the shown
schema and the other occurrences (lines referenced in the comment) and change
their definition accordingly, keeping any existing example if desired.
In `@cli.mdx`:
- Around line 379-381: The heading "Deep web research" and the following
sentence repeat the same phrase; remove the redundancy by shortening the
sentence under the "Deep web research" heading to a concise descriptor (e.g.,
"Synthesizes information from across the web into a cited report.") so the
heading remains and the body becomes a single scannable line; update the
sentence text beneath the "Deep web research" heading to the concise version and
remove the original repetitive sentence.
- Line 350: Update the documentation string "List tracked radio stations" to
explicitly indicate scope by changing it to "List globally tracked radio
stations" wherever the exact phrase appears (e.g., the title or description in
the CLI docs entry that currently reads "List tracked radio stations") so the
command description is self-documenting and unambiguous; ensure the modified
phrase is used consistently in the CLI help/MDX entry and keep formatting
identical to surrounding lines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 024fa5e7-386e-4e99-b43c-df41274ab422
📒 Files selected for processing (2)
api-reference/openapi.jsoncli.mdx
… interval/type enums Made-with: Cursor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
api-reference/openapi.json (2)
5967-5986: Consider centralizing repeated 400/401 response objects undercomponents.responses.You already centralized the schema; centralizing the full response objects too would reduce duplication and future drift across ~30 endpoints.
♻️ Suggested DRY refactor
"components": { + "responses": { + "ResearchValidationError": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "ResearchUnauthorizedError": { + "description": "Authentication failed — invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + } + }, "schemas": { ...- "400": { - "description": "Validation error (e.g., missing required query parameter `q`)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ResearchErrorResponse" - } - } - } - }, - "401": { - "description": "Authentication failed — invalid or missing API key", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ResearchErrorResponse" - } - } - } - } + "400": { "$ref": "#/components/responses/ResearchValidationError" }, + "401": { "$ref": "#/components/responses/ResearchUnauthorizedError" }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5967 - 5986, Multiple endpoints repeat identical 400 and 401 response objects; create centralized response components (e.g., components.responses.BadRequest and components.responses.Unauthorized that reference components.schemas.ResearchErrorResponse) and replace the inline response objects in the paths with $ref pointers (for example change the inline "400" and "401" response objects to "$ref": "#/components/responses/BadRequest" and "$ref": "#/components/responses/Unauthorized"). Update any occurrences across the spec so all ~30 endpoints reference these new components instead of duplicating the same content.
14976-14979: Consider re-adding explicit success enums forstatuson 200-response schemas.For several updated schemas,
statusis nowtype: stringwith only an example. Usingenum: ["success"](and optionally markingstatusas required) gives stricter SDK typing and validation.Also applies to: 15269-15272, 15542-15544, 16153-16156
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14976 - 14979, The response schemas that currently define "status" only as type: string with an example should be updated to a stricter definition: replace the loose "status": { "type": "string", "example": "success" } with "status": { "type": "string", "enum": ["success"] } and add "status" to the schema's required array so SDKs validate/tighten typing; apply this change to the shown schema and the other instances referenced (the blocks around the other occurrences noted in the comment).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@api-reference/openapi.json`:
- Around line 5967-5986: Multiple endpoints repeat identical 400 and 401
response objects; create centralized response components (e.g.,
components.responses.BadRequest and components.responses.Unauthorized that
reference components.schemas.ResearchErrorResponse) and replace the inline
response objects in the paths with $ref pointers (for example change the inline
"400" and "401" response objects to "$ref": "#/components/responses/BadRequest"
and "$ref": "#/components/responses/Unauthorized"). Update any occurrences
across the spec so all ~30 endpoints reference these new components instead of
duplicating the same content.
- Around line 14976-14979: The response schemas that currently define "status"
only as type: string with an example should be updated to a stricter definition:
replace the loose "status": { "type": "string", "example": "success" } with
"status": { "type": "string", "enum": ["success"] } and add "status" to the
schema's required array so SDKs validate/tighten typing; apply this change to
the shown schema and the other instances referenced (the blocks around the other
occurrences noted in the comment).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b420148f-6417-42ac-9483-25f201c52e5b
📒 Files selected for processing (1)
api-reference/openapi.json
Final Verification — All Schemas Match Live APITested all 30 endpoints on preview deployment and compared actual response keys against the OpenAPI schemas in this PR.
30/30 schemas match live API responses. All 30 have 200 + 400 + 401 response definitions. |
2 participants
Summary
ResearchErrorResponsecomponent ({ status: "error", error: "message" })$refexample: "success"to all response schemastatusfields for consistencySchema fixes
ResearchCareerResponsedata→career{ career: data }, not{ data }ResearchWebResponseitemscontent→snippet; addeddate,last_updatedsnippet, notcontentResearchEnrichResponseresearch_basis.citations→ top-levelcitations{ output, citations }flatResearchPeopleResultid,publishedDate,authorError responses added
All 30
/api/research/*endpoints now document:Both reference the shared
ResearchErrorResponseschema.Test plan
openapi.jsonparses as valid JSON (done locally)Made with Cursor
Summary by CodeRabbit