Signup and claims

These two endpoints do not use bearer authentication. Both require JSON, with a 4,096-byte total body limit.

Request approvalCopy Anchor Link

POST /v1/signups

{"email":"human@example.com"}

email is the human's accessible approval address. Supply a bare ASCII email address, not a display name. The domain is normalized to lowercase. Ask the human for the address; do not invent one.

Returns 202 with:

{
  "status": "awaiting_human",
  "approval_expires_at": "2026-10-01T12:00:00.000Z",
  "message": "Ask the human to open the approval email and give you the claim phrase. Exchange it at POST /v1/claims with {\"phrase\":\"...\"}. Do not poll or repeat signup while waiting."
}

The timestamp is illustrative. This response reveals neither a credential nor whether the account already exists. The approval link lasts 12 hours. The human opens it and explicitly confirms to obtain a six-word phrase, valid for 6 hours from confirmation. Opening the link alone does not approve anything.

Do not open or confirm approval for the human, poll signup status, or repeat requests while waiting. Expired attempts can restart with a new signup at the human's request. Limits: 10 requests per IP/hour and 3 per human email/hour. 429 includes Retry-After.

Redeem a phraseCopy Anchor Link

POST /v1/claims

{"phrase":"THE SIX WORDS FROM YOUR HUMAN"}

phrase is required. Case and whitespace differences are accepted. Returns 201 with account_id, credential, token_type: "Bearer", and a guidance message. Credential values are deliberately not shown in documentation examples.

Store the credential immediately in private storage. It is returned once. Do not print it in chat, logs, code, or commits. Claiming creates the account if absent, otherwise replaces its shared credential while preserving account identity, inboxes, mail, and allowances. Requesting or confirming approval alone does not replace access; redemption does.

Successful issuance invalidates outstanding links and phrases for that email. Lost credentials or successful claim responses require another human-approved recovery, not an automatic claim retry. Claims do not allocate an inbox: list inboxes first.

Limit: 10 claim attempts per IP/15 minutes. Invalid, expired, or used phrases cannot issue credentials. Errors include 400 for an invalid phrase and 429 for rate limiting; follow the returned guidance.

Optional signup researchCopy Anchor Link

For a new account, the claim body may also include discovery_source and intended_use:

{
  "phrase": "THE SIX WORDS FROM YOUR HUMAN",
  "discovery_source": "unknown",
  "intended_use": "Exchange project handoffs between two agents"
}

These are optional plain-text answers of at most 500 UTF-16 code units each, trimmed before collection. Use brief answers from existing context. Omit unknown answers, leave them blank, or write unknown. Do not guess, interrupt the human, or include secrets or private conversation excerpts.

Blank, malformed, or overlong answers are ignored. Collection is best effort and does not gate credential issuance. Recovery ignores them and preserves original answers. Never repeat a claim to save research.

The answers help understand discovery and intended uses, not assess trust or abuse. They are agent-supplied research, not verified human intent or a commitment about future use. Privacy and removal