docs: add account emails endpoint reference#114
docs: add account emails endpoint reference#114arpitgupta1214 wants to merge 4 commits intorecoupable:mainfrom
Conversation
📝 WalkthroughWalkthroughAdded a new GET /api/accounts/emails API endpoint and corresponding OpenAPI schemas, plus an MDX reference page and docs navigation entry. The endpoint accepts repeatable Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API as "API Server"
participant Auth as "Auth Service"
participant DB as "Database"
Client->>API: GET /api/accounts/emails?account_id=<id>&...
API->>Auth: Validate credentials (apiKey/bearer)
Auth-->>API: 200 OK / 401 Unauthorized
API->>DB: Query account_emails for requested account_id(s)
DB-->>API: Return rows (may be empty)
API->>Client: 200 AccountEmailsResponse / 403 / 400 / 500
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 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.
Actionable comments posted: 1
🤖 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 322-331: The OpenAPI parameter "account_id" is marked repeatable
(explode: true) but its schema is a scalar string; update the parameter
definition for "account_id" so schema.type is "array" with items.type "string"
and items.format "uuid" (preserve required:false and explode:true) so clients
will correctly send/receive multiple account_id values; adjust any examples or
docs referencing "account_id" to reflect an array of UUIDs if present.
🪄 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: 30afb5a7-f3d1-47ea-9144-a282f4b5a31e
📒 Files selected for processing (3)
api-reference/accounts/emails.mdxapi-reference/openapi.jsondocs.json
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/accounts/emails.mdx`:
- Around line 6-16: This MDX page (accounts/emails.mdx) contains custom
descriptive sections and a curl example that must be removed so the file is
frontmatter-only; edit accounts/emails.mdx to delete the prose, curl snippet,
and the authorization note so only the existing frontmatter remains, and then
verify the endpoint's description, examples, and 403 authorization behavior are
present in the OpenAPI spec (api-reference/openapi.json) so Mintlify can
auto-generate the full reference page.
In `@api-reference/openapi.json`:
- Around line 316-323: The account_id query schema currently allows an unbounded
array ("schema" with "type": "array" and "items" of
"type":"string","format":"uuid"); add a "maxItems" (and optionally "minItems" if
empty arrays are invalid) to that schema to bound cardinality — e.g., add
"maxItems": <reasonable_limit> next to the existing "items" definition (and
"minItems": 1 if needed) so tooling/validation enforces the limit; update the
schema where the "account_id" parameter is defined (look for the parameter named
"account_id" and its "schema"/"items" block) and ensure any API docs/tests
reflect the new constraints.
🪄 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: 768d68fe-466b-4693-b2af-7f599f61336e
📒 Files selected for processing (2)
api-reference/accounts/emails.mdxapi-reference/openapi.json
api-reference/accounts/emails.mdx
Outdated
| Retrieve raw `account_emails` rows for one or more accounts the authenticated caller can access. | ||
|
|
||
| Repeat the `account_id` query parameter to request multiple accounts: | ||
|
|
||
| ```bash | ||
| curl --request GET \ | ||
| --url 'https://recoup-api.vercel.app/api/accounts/emails?account_id=24994fe8-e63c-4c4a-867e-f38976e3fd31&account_id=ab1c64cd-4364-415e-abb4-04abbbda368e' \ | ||
| --header 'x-api-key: YOUR_API_KEY' | ||
| ``` | ||
|
|
||
| The server validates access for every requested `account_id`. If any requested account is unauthorized, the request returns `403`. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Remove custom content sections—API reference pages should be frontmatter-only.
This file contains custom description text, curl examples, and authorization notes. API reference MDX pages should only contain frontmatter and let Mintlify auto-generate all content from the OpenAPI specification. As per coding guidelines, "API reference MDX pages should be frontmatter-only - do NOT add custom sections (Overview, Availability, etc.) and let Mintlify auto-generate everything from the OpenAPI spec".
📝 Proposed fix to remove custom sections
---
title: 'Get Account Emails'
openapi: 'GET /api/accounts/emails'
---
-
-Retrieve raw `account_emails` rows for one or more accounts the authenticated caller can access.
-
-Repeat the `account_id` query parameter to request multiple accounts:
-
-```bash
-curl --request GET \
- --url 'https://recoup-api.vercel.app/api/accounts/emails?account_id=24994fe8-e63c-4c4a-867e-f38976e3fd31&account_id=ab1c64cd-4364-415e-abb4-04abbbda368e' \
- --header 'x-api-key: YOUR_API_KEY'
-```
-
-The server validates access for every requested `account_id`. If any requested account is unauthorized, the request returns `403`.Ensure that the OpenAPI spec at api-reference/openapi.json contains complete documentation for this endpoint, including descriptions, examples, and authorization behavior, so Mintlify can auto-generate the full reference page.
🧰 Tools
🪛 Betterleaks (1.1.1)
[high] 11-13: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/accounts/emails.mdx` around lines 6 - 16, This MDX page
(accounts/emails.mdx) contains custom descriptive sections and a curl example
that must be removed so the file is frontmatter-only; edit accounts/emails.mdx
to delete the prose, curl snippet, and the authorization note so only the
existing frontmatter remains, and then verify the endpoint's description,
examples, and 403 authorization behavior are present in the OpenAPI spec
(api-reference/openapi.json) so Mintlify can auto-generate the full reference
page.
| "schema": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string", | ||
| "format": "uuid" | ||
| } | ||
| }, | ||
| "explode": true |
There was a problem hiding this comment.
Bound account_id array size in schema.
account_id is repeatable but unbounded. Add maxItems (and optionally minItems if empty requests are not meaningful) to prevent unbounded query cardinality in tooling and validation.
Proposed fix
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
- }
+ },
+ "maxItems": 100
},
"explode": true📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "type": "string", | |
| "format": "uuid" | |
| } | |
| }, | |
| "explode": true | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "type": "string", | |
| "format": "uuid" | |
| }, | |
| "maxItems": 100 | |
| }, | |
| "explode": true |
🧰 Tools
🪛 Checkov (3.2.513)
[medium] 316-321: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 316 - 323, The account_id query
schema currently allows an unbounded array ("schema" with "type": "array" and
"items" of "type":"string","format":"uuid"); add a "maxItems" (and optionally
"minItems" if empty arrays are invalid) to that schema to bound cardinality —
e.g., add "maxItems": <reasonable_limit> next to the existing "items" definition
(and "minItems": 1 if needed) so tooling/validation enforces the limit; update
the schema where the "account_id" parameter is defined (look for the parameter
named "account_id" and its "schema"/"items" block) and ensure any API docs/tests
reflect the new constraints.
![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 2 files (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/accounts/emails.mdx">
<violation number="1" location="api-reference/accounts/emails.mdx:6">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
This MDX file should be frontmatter-only per the repository convention (`AGENTS.md` → "CRITICAL: API reference MDX pages should be frontmatter-only"). All other account endpoint pages (`get.mdx`, `create.mdx`, `id.mdx`, `update.mdx`, `add-artist.mdx`) follow this pattern. The description, parameter docs, curl example, and response behavior belong in `openapi.json` and will be auto-generated by Mintlify from the spec.</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.
| openapi: 'GET /api/accounts/emails' | ||
| --- | ||
|
|
||
| Retrieve raw `account_emails` rows for one or more accounts the authenticated caller can access. |
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
This MDX file should be frontmatter-only per the repository convention (AGENTS.md → "CRITICAL: API reference MDX pages should be frontmatter-only"). All other account endpoint pages (get.mdx, create.mdx, id.mdx, update.mdx, add-artist.mdx) follow this pattern. The description, parameter docs, curl example, and response behavior belong in openapi.json and will be auto-generated by Mintlify from the spec.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/accounts/emails.mdx, line 6:
<comment>This MDX file should be frontmatter-only per the repository convention (`AGENTS.md` → "CRITICAL: API reference MDX pages should be frontmatter-only"). All other account endpoint pages (`get.mdx`, `create.mdx`, `id.mdx`, `update.mdx`, `add-artist.mdx`) follow this pattern. The description, parameter docs, curl example, and response behavior belong in `openapi.json` and will be auto-generated by Mintlify from the spec.</comment>
<file context>
@@ -2,3 +2,15 @@
openapi: 'GET /api/accounts/emails'
---
+
+Retrieve raw `account_emails` rows for one or more accounts the authenticated caller can access.
+
+Repeat the `account_id` query parameter to request multiple accounts:
</file context>
|
Closing this migration PR. We are switching to a new plan for the account emails change. |
1 participant
Summary
Testing
Summary by cubic
Added API reference for
GET /api/accounts/emailsto list account email rows with per-account access checks. The endpoint now requires at least oneaccount_id; docs, OpenAPI, and nav updated.New Features
GET /api/accounts/emailswith required, repeatableaccount_idquery; validates access for each ID; supportsapiKeyAuthandbearerAuth.200→AccountEmailsResponse(array; empty if no matches);401→StatusErrorResponse;400(missingaccount_id)/403/500→AccountEmailsErrorResponse.account_idexample and requirement noted.Bug Fixes
account_idquery parameter (arraywithexplode: true).Written for commit 0912f6f. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation