Skip to content

docs: add account emails endpoint reference #114

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

Closed
arpitgupta1214 wants to merge 4 commits into from
Closed

docs: add account emails endpoint reference #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fd0b4b2
docs: add account emails endpoint reference
arpitgupta1214 Apr 7, 2026
66439cd
docs: fix repeated account_id parameter schema
arpitgupta1214 Apr 7, 2026
f9652dd
docs: update account emails auth contract
arpitgupta1214 Apr 7, 2026
0912f6f
docs: require account ids for account emails
arpitgupta1214 Apr 7, 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
16 changes: 16 additions & 0 deletions api-reference/accounts/emails.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: 'Get Account Emails'
openapi: 'GET /api/accounts/emails'
---

Retrieve raw `account_emails` rows for one or more accounts the authenticated caller can access.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

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>
Fix with Cubic


Provide at least one `account_id` query parameter. Repeat it 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 no `account_id` values are provided, the request returns `400`. If any requested account is unauthorized, the request returns `403`.
150 changes: 150 additions & 0 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,87 @@
}
}
},
"/api/accounts/emails": {
"get": {
"description": "Retrieve raw account email rows for one or more account IDs after verifying that the authenticated caller can access every requested account.",
"parameters": [
{
"name": "account_id",
"in": "query",
"description": "Account ID to look up. Repeat this query parameter to fetch multiple rows. At least one account_id is required, and the authenticated caller must be allowed to access every requested account.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"explode": true
Comment on lines +316 to +323
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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.

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

}
],
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Account email rows retrieved successfully. Returns an empty array when the requested accounts are authorized but have no matching account_emails rows.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountEmailsResponse"
}
}
}
},
"400": {
"description": "Bad request - at least one account_id query parameter is required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountEmailsErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized - missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden - authenticated account does not have access to one or more requested account_id values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountEmailsErrorResponse"
}
}
}
},
"500": {
"description": "Unexpected internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountEmailsErrorResponse"
}
}
}
}
}
}
},
"/api/accounts/id": {
"get": {
"description": "Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.",
Expand Down Expand Up @@ -7623,6 +7704,26 @@
}
}
},
"StatusErrorResponse": {
"type": "object",
"required": [
"status",
"error"
],
"properties": {
"status": {
"type": "string",
"enum": [
"error"
],
"description": "Status of the request"
},
"error": {
"type": "string",
"description": "Error message describing what went wrong"
}
}
},
"AccountErrorResponse": {
"type": "object",
"required": [
Expand All @@ -7643,6 +7744,55 @@
}
}
},
"AccountEmailRow": {
"type": "object",
"required": [
"id",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the account email row"
},
"account_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Account ID associated with the email row"
},
"email": {
"type": "string",
"format": "email",
"nullable": true,
"description": "Email address associated with the account"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the row was last updated"
}
}
},
"AccountEmailsResponse": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountEmailRow"
}
},
"AccountEmailsErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Error message describing what went wrong"
}
}
},
"CreateAccountRequest": {
"type": "object",
"properties": {
Expand Down
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,7 @@
"group": "Accounts",
"pages": [
"api-reference/accounts/get",
"api-reference/accounts/emails",
"api-reference/accounts/id",
"api-reference/accounts/create",
"api-reference/accounts/update",
Expand Down