RecoupGet a Free AuditFree Audit

Agents

Agents

Programmatic agent onboarding — sign up and obtain API keys in one call, no dashboard, no human in the loop.

On this page

Quickest start

Get a working API key in a single unauthenticated request:

bash
curl -X POST "https://api.recoupable.dev/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.

How it works

Two unauthenticated endpoints power agent onboarding:

  • POST /api/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 — 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://api.recoupable.dev/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://api.recoupable.dev/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://api.recoupable.dev/api/tasks" \
  -H "x-api-key: YOUR_API_KEY"

See Authentication for the full authentication model, including organization access and Bearer token support, and Quickstart for your first end-to-end request.