docs: tighten research endpoint schemas to match handler enforcement

[sweetmantech]

Summary

Align `api-reference/openapi/research.json` with the validation the research handlers in recoupable/api#366 actually enforce. No behavior change — docs-only cleanup that surfaces existing enums and constraints previously hidden.

Enums added

• `/research/metrics` → `source` (14-item enum: spotify, tiktok, youtube_*, etc.)
• `/research/playlist` → `platform` (5-item enum incl. youtube)
• `/research/playlists` → `platform` (5-item enum)
• `/research/track/playlists` → `platform` (4-item — no youtube, matching handler) + `status` (current|past)
• `/research/similar` → `audience`, `genre`, `mood`, `musicality` (high|medium|low)

Missing query params added

• `/research/playlists` → `indie`, `majorCurator`, `popularIndie`, `personalized`, `chart`

Validation constraints

• `/research/charts` → `platform` pattern `^[a-z]+$`
• `/research/discover` → `country` length 2, `limit` 1–100
• `ResearchExtractRequest.urls` → `minItems: 1`

Test plan

• JSON validates
• `npx mintlify@latest dev` — spot-check the tightened pages render without errors

🤖 Generated with Claude Code

---

Summary by cubic

Tightens research endpoint schemas in api-reference/openapi/research.json to match handler validation. Adds enums, missing playlist filters, and input constraints so the docs reflect real behavior; no API change.

• Bug Fixes
  • Enums: /research/metrics source (14 values); playlist platform for /research/playlist and /research/playlists (spotify|applemusic|deezer|amazon|youtube); /research/track/playlists platform (spotify|applemusic|deezer|amazon) + status (current|past); /research/similar weights (audience, genre, mood, musicality) set to high|medium|low with default medium.
  • Query params: documents /research/playlists filters indie, majorCurator, popularIndie, personalized, chart.
  • Validation: /research/charts platform pattern ^[a-z]+$; /research/discover country length 2 and limit 1–100; ResearchExtractRequest.urls now minItems: 1.

^{Written for commit a586cb7. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added filtering options for playlist results (indie, majorCurator, popularIndie, personalized, chart).

• Bug Fixes

  • Enhanced validation constraints for API parameters including country codes, result limits, and URL requests.
  • Applied default values to similarity query parameters for consistency.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated OpenAPI parameter validation and defaults for research API endpoints in research.json. Added pattern constraints to platform parameter, length constraints to country parameter, numeric bounds to limit parameter, new boolean query flags to /api/research/playlists, default values to parameters in /api/research/similar, and minimum item validation to urls in ResearchExtractRequest schema.

Changes

Cohort / File(s)	Summary
Platform Parameter Validation api-reference/openapi/research.json	Added pattern: ^[a-z]+$ constraint to the platform query parameter for GET /api/research/charts to enforce lowercase letters only.
Country & Limit Parameters api-reference/openapi/research.json	Added minLength: 2, maxLength: 2 to country parameter and minimum: 1, maximum: 100 bounds to limit parameter for GET /api/research/discover.
Playlist Query Flags api-reference/openapi/research.json	Added five new boolean query parameters (indie, majorCurator, popularIndie, personalized, chart) to GET /api/research/playlists.
Similar Endpoint Defaults api-reference/openapi/research.json	Added default: "medium" to audience, genre, mood, and musicality query parameters in GET /api/research/similar.
Extract Request Validation api-reference/openapi/research.json	Added minItems: 1 constraint to urls property in ResearchExtractRequest schema alongside existing maxItems: 10.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix: harden research API response schemas and add error responses #132: Updates research API parameter and schema changes in the same OpenAPI file (/api/research/charts query params and Research extract request schemas).
• docs: add Research API and CLI reference #85: Adds and documents the Research API specification with api-reference/openapi.json and MDX documentation pages for /api/research/* endpoints.

Poem

🐰 With whiskers twitching, constraints tight,
The API bounds now shine so bright!
Patterns, lengths, and limits gleam,
Validation's every dreamer's dream!
Hopping forward, rules aligned—
Safer queries, well-designed! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: tightening OpenAPI schemas in the research endpoint documentation to enforce handler validation constraints.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/research-tighten-schemas

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

api-reference/openapi/research.json (1)

4026-4027: Update urls description text to include the new minimum.

Schema now enforces at least one URL, but the description still only states max count. Consider making the text reflect both bounds.

✏️ Proposed doc-text tweak

-            "description": "URLs to extract content from (max 10).",
+            "description": "URLs to extract content from (min 1, max 10).",

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/research.json` around lines 4026 - 4027, Update the
"urls" property description to reflect both bounds: mention that the array
requires at least 1 URL and allows up to 10 (e.g., "URLs to extract content from
(min 1, max 10)"). Locate the "urls" schema description in the OpenAPI JSON (the
property named "urls") and replace the existing text that only mentions the max
with a concise description that includes both min and max constraints.

🤖 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/research.json`:
- Around line 4026-4027: Update the "urls" property description to reflect both
bounds: mention that the array requires at least 1 URL and allows up to 10
(e.g., "URLs to extract content from (min 1, max 10)"). Locate the "urls" schema
description in the OpenAPI JSON (the property named "urls") and replace the
existing text that only mentions the max with a concise description that
includes both min and max constraints.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5b2833cc-5cfd-4dcc-892b-892b233e8872

📥 Commits

Reviewing files that changed from the base of the PR and between 986287c and a586cb7.

📒 Files selected for processing (1)

• api-reference/openapi/research.json

[cubic-dev-ai]

No issues found across 1 file