recoupable · sweetmantech · Apr 12, 2026 · Apr 6, 2026 · Apr 11, 2026 · Apr 11, 2026
@@ -0,0 +1,96 @@
+---
+title: 'Agents'
+description: 'Programmatic agent onboarding — sign up and obtain API keys in one call, no dashboard, no human in the loop.'
+---
+
+## Quickest start
+
+Get a working API key in a single unauthenticated request:
+
+```bash
+curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}'
+```
+
+Response:
+
+```json
+{
+  "account_id": "123e4567-e89b-12d3-a456-426614174000",
+  "api_key": "recoup_sk_abc123...",
+  "message": "If this is a new agent+ email, your API key is included. Otherwise, check your email for a verification code."
+}
+```
+
+That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done.
+
+<Tip>
+**One-liner — sign up and export the key in one shot.** Drop this into your shell and you'll have `$RECOUP_API_KEY` ready to use on the next line:
+
+```bash
+export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
+```
+
+Verify it worked:
+
+```bash
+curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
+```
+</Tip>
+
+<Tip>
+The `agent+{unique-suffix}@recoupable.com` shape is the recommended path for agents — it always returns an API key instantly, with no email verification required. Combining `$(date +%s)` with `$RANDOM` guarantees a fresh, collision-free address on every call (including multiple signups within the same second) and is portable across macOS and Linux shells.
+</Tip>
+
+## How it works
+
+Two unauthenticated endpoints power agent onboarding:
+
+- **[`POST /api/agents/signup`](/api-reference/agents/signup)** — Register with an email address. Emails with the `agent+` prefix that have never been seen before receive an API key immediately. Any other email (or a previously-used `agent+` address) receives a 6-digit verification code via email.
+- **[`POST /api/agents/verify`](/api-reference/agents/verify)** — Submit the verification code to receive an API key.
+
+Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones.
+
+## Standard signup (email verification)
+
+If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address:
+
+Step 1 — request a verification code:
+
+```bash
+curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "you@example.com"}'
+```
+
+Step 2 — submit the 6-digit code from the verification email:
+
+```bash
+curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "you@example.com", "code": "123456"}'
+```
+
+Response:
+
+```json
+{
+  "account_id": "123e4567-e89b-12d3-a456-426614174000",
+  "api_key": "recoup_sk_abc123...",
+  "message": "Verified"
+}
+```
+
+## Using your API key
+
+Pass the returned `api_key` in the `x-api-key` header on every authenticated request:
+
+```bash
+curl -X GET "https://recoup-api.vercel.app/api/tasks" \
+  -H "x-api-key: YOUR_API_KEY"
+```
+
+See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.
@@ -0,0 +1,4 @@
+---
+title: 'Agent Signup'
+openapi: "/api-reference/openapi/accounts.json POST /api/agents/signup"
+---
@@ -0,0 +1,4 @@
+---
+title: 'Verify Agent Email'
+openapi: "/api-reference/openapi/accounts.json POST /api/agents/verify"
+---
@@ -1463,6 +1463,84 @@
           }
         }
       }
+    },
+    "/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.",
+        "security": [],
+        "requestBody": {
+          "description": "Agent email to register",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AgentSignupRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Signup processed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentSignupResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/agents/verify": {
+      "post": {
+        "description": "Verify an agent's email with the code sent during signup. Returns an API key on success.",
+        "security": [],
+        "requestBody": {
+          "description": "Email and verification code",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AgentVerifyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Verification successful",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentVerifyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or expired verification code",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many failed verification attempts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -2649,6 +2727,97 @@
             "description": "UUID of the account to update the pulse for. Only applicable when the authenticated account has access to multiple accounts via organization membership. If not provided, updates the pulse for the API key's own account."
           }
         }
+      },
+      "AgentSignupRequest": {
+        "type": "object",
+        "required": [
+          "email"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "The agent email address. Emails with the agent+ prefix (e.g. agent+mybot@example.com) get an API key immediately on first signup.",
+            "example": "agent+mybot@example.com"
+          }
+        }
+      },
+      "AgentSignupResponse": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "message"
+        ],
+        "properties": {
+          "account_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The account ID for the registered agent.",
+            "example": "123e4567-e89b-12d3-a456-426614174000"
+          },
+          "api_key": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "API key returned immediately for new agent+ prefix emails. Null for all other cases — check your email for a verification code.",
+            "example": "recoup_sk_abc123..."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable status message.",
+            "example": "If this is a new agent+ email, your API key is included. Otherwise, check your email for a verification code."
+          }
+        }
+      },
+      "AgentVerifyRequest": {
+        "type": "object",
+        "required": [
+          "email",
+          "code"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "The email address used during signup.",
+            "example": "you@example.com"
+          },
+          "code": {
+            "type": "string",
+            "minLength": 6,
+            "maxLength": 6,
+            "pattern": "^[0-9]{6}$",
+            "description": "The 6-digit verification code sent to the email.",
+            "example": "123456"
+          }
+        }
+      },
+      "AgentVerifyResponse": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "api_key",
+          "message"
+        ],
+        "properties": {
+          "account_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The account ID for the verified agent.",
+            "example": "123e4567-e89b-12d3-a456-426614174000"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "API key for the verified account.",
+            "example": "recoup_sk_abc123..."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable status message.",
+            "example": "Verified"
+          }
+        }
       }
     }
   }

@@ -14,6 +14,10 @@ Every request to the Recoup API must be authenticated using exactly one of two m
 
 Providing both headers in the same request will result in a `401` error.
 
+<Note>
+Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.
+</Note>
+
 ---
 
 ## API Keys

@@ -26,6 +26,7 @@
           {
             "group": "Agents",
             "pages": [
+              "agents",
               "content-agent"
             ]
           }
@@ -248,6 +249,13 @@
       {
         "tab": "Accounts",
         "groups": [
+          {
+            "group": "Agent Onboarding",
+            "pages": [
+              "api-reference/agents/signup",
+              "api-reference/agents/verify"
+            ]
+          },
           {
             "group": "Connectors",
             "pages": [

@@ -7,6 +7,18 @@ description: "Use the Recoup API to build your record label. Access research, co
 
 Use the Recoup API to build your record label. Generate content, Access artist analytics, Manage catalogs, Team chats, and task automation to power your record labels.
 
+## Quickest start — one curl call
+
+Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop.
+
+```bash
+export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
+```
+
+`$RECOUP_API_KEY` is now ready to pass in the `x-api-key` header on any request. See the [Agents guide](/agents) for the full signup and verification flow.
+
 ## What is Recoup?
 
 Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.
@@ -23,7 +35,7 @@ https://recoup-api.vercel.app/api
 
 ## Authentication
 
-All API endpoints are authenticated using an API key passed in the `x-api-key` header.
+Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key.
 
 1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys)
 2. Sign in with your account
@@ -41,7 +53,14 @@ Keep your API key secure. Do not share it publicly or commit it to version contr
 
 ## Get Started
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
+  <Card
+    title="Agent Signup"
+    icon="user-plus"
+    href="/agents"
+  >
+    Get an API key in one curl call. The fastest path for AI agents — no dashboard required.
+  </Card>
   <Card
     title="Quickstart"
     icon="rocket"
@@ -151,6 +170,7 @@ If you are an LLM navigating these docs, here is a summary of the endpoint struc
 - **`/api/organizations/*`** — Organizations (list, create, add-artist)
 - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)
 - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)
+- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required
 
 Base URL: `https://recoup-api.vercel.app/api`
-Original file line number
+Diff line change
@@ Expand Up @@
     Providing both headers in the same request will result in a `401` error.
+    <Note>
+    Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.
+    </Note>
     ---
     ## API Keys
@@ Expand Down @@