From 904bb006b77a4eb2074f9e9e64642eda3aba8d8f Mon Sep 17 00:00:00 2001 From: john Date: Wed, 6 May 2026 09:43:35 +0700 Subject: [PATCH 1/2] docs(agents): add GET /api/agents endpoint and update navigation - Introduced a new GET endpoint for retrieving agent linkage by social IDs, including detailed request parameters and response schemas. - Updated the documentation to include the new endpoint in the Agents Onboarding navigation group, enhancing the API reference for better accessibility. Co-authored-by: Claude Opus 4.7 (1M context) --- api-reference/agents/get.mdx | 4 + api-reference/openapi/accounts.json | 115 ++++++++++++++++++++++++++++ docs.json | 3 +- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 api-reference/agents/get.mdx diff --git a/api-reference/agents/get.mdx b/api-reference/agents/get.mdx new file mode 100644 index 00000000..770b1176 --- /dev/null +++ b/api-reference/agents/get.mdx @@ -0,0 +1,4 @@ +--- +title: List agent links by social IDs +openapi: "/api-reference/openapi/accounts.json GET /api/agents" +--- diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 67652285..9f2164fb 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -1613,6 +1613,79 @@ } } }, + "/api/agents": { + "get": { + "description": "Returns agent linkage for one or more artist social IDs. Pass each ID as a repeated `socialId` query parameter (UUID of a row in `socials`). Each element includes a platform `type` (or `wrapped` when one agent spans multiple socials), the agent `agentId`, and `updated_at`. Authentication via x-api-key or Authorization Bearer token.", + "parameters": [ + { + "name": "socialId", + "in": "query", + "description": "Artist social ID (UUID). Repeat this query parameter to request multiple IDs.", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1 + }, + "style": "form", + "explode": true + } + ], + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Agents retrieved successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetAgentsResponse" + } + } + } + }, + "400": { + "description": "Missing or invalid query parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentsGetErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountErrorResponse" + } + } + } + }, + "500": { + "description": "Failed to load agents", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentsGetErrorResponse" + } + } + } + } + } + } + }, "/api/agents/signup": { "post": { "description": "Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.\n\n**Tip:** If you're unsure what email to register, generate a unique `agent+{suffix}@recoupable.com` address (e.g. `agent+1744410896-28439@recoupable.com`, combining a Unix timestamp with a random integer). This guarantees a fresh `agent+` address on every call — including multiple signups within the same second — and returns an API key instantly with no email verification required.", @@ -2796,6 +2869,48 @@ } } }, + "GetAgentsItem": { + "type": "object", + "required": [ + "type", + "agentId", + "updated_at" + ], + "properties": { + "type": { + "type": "string", + "description": "Platform label derived from the social profile URL, or `wrapped` when one agent is linked to multiple socials.", + "example": "spotify" + }, + "agentId": { + "type": "string", + "format": "uuid", + "description": "Agent row ID." + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "GetAgentsResponse": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GetAgentsItem" + } + }, + "AgentsGetErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Error message" + } + } + }, "CreateSubscriptionSessionRequest": { "type": "object", "required": [ diff --git a/docs.json b/docs.json index 147ee004..4948c28c 100644 --- a/docs.json +++ b/docs.json @@ -226,7 +226,8 @@ "group": "Agent Onboarding", "pages": [ "api-reference/agents/signup", - "api-reference/agents/verify" + "api-reference/agents/verify", + "api-reference/agents/get" ] }, { From 529f77d86c07853341fb5ab0109a9da1132489d0 Mon Sep 17 00:00:00 2001 From: john Date: Wed, 6 May 2026 10:40:43 +0700 Subject: [PATCH 2/2] docs(agents): update OpenAPI path for GET /api/agents endpoint - Simplified the OpenAPI path in the documentation for the GET /api/agents endpoint to enhance clarity and consistency. --- api-reference/agents/get.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/agents/get.mdx b/api-reference/agents/get.mdx index 770b1176..487188a6 100644 --- a/api-reference/agents/get.mdx +++ b/api-reference/agents/get.mdx @@ -1,4 +1,4 @@ --- title: List agent links by social IDs -openapi: "/api-reference/openapi/accounts.json GET /api/agents" +openapi: 'GET /api/agents' ---