diff --git a/agents.mdx b/agents.mdx new file mode 100644 index 0000000..8bbf1f0 --- /dev/null +++ b/agents.mdx @@ -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. + + +**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 +``` + + + +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. + + +## 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. diff --git a/api-reference/agents/signup.mdx b/api-reference/agents/signup.mdx new file mode 100644 index 0000000..1d3b603 --- /dev/null +++ b/api-reference/agents/signup.mdx @@ -0,0 +1,4 @@ +--- +title: 'Agent Signup' +openapi: "/api-reference/openapi/accounts.json POST /api/agents/signup" +--- diff --git a/api-reference/agents/verify.mdx b/api-reference/agents/verify.mdx new file mode 100644 index 0000000..2dc6ddf --- /dev/null +++ b/api-reference/agents/verify.mdx @@ -0,0 +1,4 @@ +--- +title: 'Verify Agent Email' +openapi: "/api-reference/openapi/accounts.json POST /api/agents/verify" +--- diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 2bcb001..9bd3a76 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -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" + } + } } } } diff --git a/authentication.mdx b/authentication.mdx index c25d42f..e7b7850 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -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. + +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. + + --- ## API Keys diff --git a/docs.json b/docs.json index 90caf0d..a78bcd0 100644 --- a/docs.json +++ b/docs.json @@ -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": [ diff --git a/index.mdx b/index.mdx index 8290ccb..62bb714 100644 --- a/index.mdx +++ b/index.mdx @@ -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 - + + + Get an API key in one curl call. The fastest path for AI agents — no dashboard required. + +The `agent+{timestamp}@recoupable.com` shape is the fastest path for agents — it guarantees a fresh `agent+` address and returns an API key instantly without email verification. + -1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account if you haven't already +For the full signup + email-verification flow, see the [Agents guide](/agents). -### Step 2: Create Your API Key +## Base URL -1. On the API Keys page, you'll see a form to create a new API key -2. Enter a descriptive name for your API key (e.g., "My Development Key", "Production API Key") -3. Click the "Create API Key" button +All API requests should be made to: - -Copy and securely store your API key immediately - it will only be shown once! - +```bash +https://recoup-api.vercel.app/api +``` -### Step 3: Use Your API Key +## Your First Request -Once you have your API key, include it in the `x-api-key` header for all authenticated requests. Here's a simple example that retrieves your scheduled tasks: +Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: @@ -119,6 +122,19 @@ console.log(data.tasks); For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). +## Prefer the dashboard? + +If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: + +1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys) +2. Sign in with your account +3. Enter a descriptive name (e.g. "Production Server") +4. Click **Create API Key** + + +Copy and securely store your API key immediately — it will only be shown once. + + ## Next Steps With your API key ready, you can now: