Agent Sign-up

An AI agent (a skill, an MCP client, a coding assistant) can create a threadapi account for its user and get an API key without a browser. The user confirms by reading a 6-digit code from their email back to the agent.

1. Ask the user for their email address.
2. POST https://threadapi.dev/api/agent/signup with the email. threadapi emails a code and returns a signup_token.
3. Ask the user for the code.
4. POST https://threadapi.dev/api/agent/verify with the token and the code. The response holds the new api_key.
5. Store the key where the user’s tools can read it, for example as THREADAPI_API_KEY, and use it as a Bearer token.

1. Request a code

curl -s -X POST https://threadapi.dev/api/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

{
  "status": "code_sent",
  "signup_token": "eyJwdXJwb3NlIjoi…",
  "expires_in": 600,
  "next": "A 6-digit code was emailed to user@example.com. Ask the user for it, then POST …"
}

The token and the code are valid for 10 minutes. The answer is the same whether or not the email already has an account.

2. Verify the code and get the key

curl -s -X POST https://threadapi.dev/api/agent/verify \
  -H "Content-Type: application/json" \
  -d '{"signup_token": "<signup_token>", "code": "123456"}' \
  -o threadapi-signup.json

201 Created:

{
  "status": "account_created",
  "api_key": "tapi_…",
  "credits": 100,
  "limits": { "requests_per_second": 1, "requests_per_day": 100 },
  "next": "Store api_key where the user's tools can read it …",
  "example_request": "GET https://api.threadapi.dev/v1/reddit/post?url=https://www.reddit.com/r/programming/comments/1x144ok/&format=md",
  "docs": "https://docs.threadapi.dev",
  "notes": "The account has 100 free credits; only successful requests use credits. …"
}

The user can sign in at threadapi.dev with the same email to see usage, manage keys, and buy credits.

Existing accounts

If the email already has a threadapi account, /api/agent/verify answers 409 account_exists once the code is correct, and no key is created. The user signs in at threadapi.dev/auth/login and creates a key at threadapi.dev/app/api-keys.

Free credits and limits

New accounts get 100 free credits, once per email address: a +tag or a Gmail address with dots counts as the same mailbox. Outside large email providers, only a few new accounts per email domain get them each day. Until the account buys a pack, its keys can make 1 request per second and 100 requests per day (UTC); any credit pack removes the daily limit.

Errors

Errors use the API’s standard envelope:

{
  "error": {
    "code": "invalid_code",
    "message": "That code is wrong. Ask the user to check the email and try again. …",
    "retryable": false
  }
}

“Start over” means calling /api/agent/signup again, which sends a new code.