From fd0b4b28349cc950723a4d75931ac0817be5793b Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 8 Apr 2026 01:52:03 +0530 Subject: [PATCH 1/4] docs: add account emails endpoint reference --- api-reference/accounts/emails.mdx | 4 + api-reference/openapi.json | 157 ++++++++++++++++++++++++++++++ docs.json | 1 + 3 files changed, 162 insertions(+) create mode 100644 api-reference/accounts/emails.mdx diff --git a/api-reference/accounts/emails.mdx b/api-reference/accounts/emails.mdx new file mode 100644 index 0000000..da8fbc1 --- /dev/null +++ b/api-reference/accounts/emails.mdx @@ -0,0 +1,4 @@ +--- +title: 'Get Account Emails' +openapi: 'GET /api/accounts/emails' +--- diff --git a/api-reference/openapi.json b/api-reference/openapi.json index cbca4f8..a4901fc 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -304,6 +304,94 @@ } } }, + "/api/accounts/emails": { + "get": { + "description": "Retrieve raw account email rows for one or more account IDs after verifying that the authenticated caller has access to the provided artist account.", + "parameters": [ + { + "name": "artist_account_id", + "in": "query", + "description": "Artist account ID used to verify the caller has access to view these account emails.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "account_id", + "in": "query", + "description": "Account ID to look up. Repeat this query parameter to fetch multiple rows.", + "required": false, + "schema": { + "type": "string", + "format": "uuid" + }, + "explode": true + } + ], + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Account email rows retrieved successfully. Returns an empty array when no matching rows are found, including when no account_id parameters are provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountEmailsResponse" + } + } + } + }, + "400": { + "description": "Bad request - artist_account_id is missing", + "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 the provided artist account", + "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.", @@ -7623,6 +7711,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": [ @@ -7643,6 +7751,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": { diff --git a/docs.json b/docs.json index 7fa83a6..5680e77 100644 --- a/docs.json +++ b/docs.json @@ -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", From 66439cde5fd27be8d53e76f4bf36385980d6c10e Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 8 Apr 2026 02:01:47 +0530 Subject: [PATCH 2/4] docs: fix repeated account_id parameter schema --- api-reference/openapi.json | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index a4901fc..d2ed718 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -324,8 +324,11 @@ "description": "Account ID to look up. Repeat this query parameter to fetch multiple rows.", "required": false, "schema": { - "type": "string", - "format": "uuid" + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } }, "explode": true } From f9652dd27c505459ddd6d0755c6dbc421001c90a Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 8 Apr 2026 02:57:41 +0530 Subject: [PATCH 3/4] docs: update account emails auth contract --- api-reference/accounts/emails.mdx | 12 ++++++++++++ api-reference/openapi.json | 18 ++++-------------- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/api-reference/accounts/emails.mdx b/api-reference/accounts/emails.mdx index da8fbc1..c2710c4 100644 --- a/api-reference/accounts/emails.mdx +++ b/api-reference/accounts/emails.mdx @@ -2,3 +2,15 @@ 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`. diff --git a/api-reference/openapi.json b/api-reference/openapi.json index d2ed718..db44d64 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -306,22 +306,12 @@ }, "/api/accounts/emails": { "get": { - "description": "Retrieve raw account email rows for one or more account IDs after verifying that the authenticated caller has access to the provided artist account.", + "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": "artist_account_id", - "in": "query", - "description": "Artist account ID used to verify the caller has access to view these account emails.", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, { "name": "account_id", "in": "query", - "description": "Account ID to look up. Repeat this query parameter to fetch multiple rows.", + "description": "Account ID to look up. Repeat this query parameter to fetch multiple rows. The authenticated caller must be allowed to access every requested account.", "required": false, "schema": { "type": "array", @@ -353,7 +343,7 @@ } }, "400": { - "description": "Bad request - artist_account_id is missing", + "description": "Bad request - invalid query parameters", "content": { "application/json": { "schema": { @@ -373,7 +363,7 @@ } }, "403": { - "description": "Forbidden - authenticated account does not have access to the provided artist account", + "description": "Forbidden - authenticated account does not have access to one or more requested account_id values", "content": { "application/json": { "schema": { From 0912f6fddcd9a858a4eb784eb0b208e61aaa2772 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 8 Apr 2026 03:06:25 +0530 Subject: [PATCH 4/4] docs: require account ids for account emails --- api-reference/accounts/emails.mdx | 4 ++-- api-reference/openapi.json | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api-reference/accounts/emails.mdx b/api-reference/accounts/emails.mdx index c2710c4..100292c 100644 --- a/api-reference/accounts/emails.mdx +++ b/api-reference/accounts/emails.mdx @@ -5,7 +5,7 @@ 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: +Provide at least one `account_id` query parameter. Repeat it to request multiple accounts: ```bash curl --request GET \ @@ -13,4 +13,4 @@ curl --request GET \ --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`. +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`. diff --git a/api-reference/openapi.json b/api-reference/openapi.json index db44d64..c107729 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -311,8 +311,8 @@ { "name": "account_id", "in": "query", - "description": "Account ID to look up. Repeat this query parameter to fetch multiple rows. The authenticated caller must be allowed to access every requested account.", - "required": false, + "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": { @@ -333,7 +333,7 @@ ], "responses": { "200": { - "description": "Account email rows retrieved successfully. Returns an empty array when no matching rows are found, including when no account_id parameters are provided.", + "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": { @@ -343,7 +343,7 @@ } }, "400": { - "description": "Bad request - invalid query parameters", + "description": "Bad request - at least one account_id query parameter is required", "content": { "application/json": { "schema": {