diff --git a/api-reference/accounts/emails.mdx b/api-reference/accounts/emails.mdx new file mode 100644 index 0000000..100292c --- /dev/null +++ b/api-reference/accounts/emails.mdx @@ -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. + +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`. diff --git a/api-reference/openapi.json b/api-reference/openapi.json index cbca4f8..c107729 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -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 + } + ], + "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.", @@ -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": [ @@ -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": { 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",