Find the approval page
POST /v1/signups
Read as Markdown ↗POST /v1/signups
No bearer authentication. Human approval is required before Claim redemption.
Agents can give humans https://cherami.to/claim directly, or call POST /v1/signups with an empty object:
Returns 202 with status: "awaiting_human", approval_url: "https://cherami.to/claim", and a guidance message. No email is sent and no account or pending request is created. Unknown fields return 400 invalid_request.
The human signs in and explicitly approves account-wide API access. The page shows the verified email. Existing keys keep working when another key is issued. A recent sign-in or Clerk reverification is required. It displays a six-word phrase once, valid for 6 hours. The human chooses which agent receives it.
Opening the page grants nothing. Do not ask for sign-in codes, approve for the human, or poll for signup status. Limit: 10 discovery requests per IP/hour; 10 browser approval requests per IP/15 minutes. 429 includes Retry-After.
Request body
JSON object. Total UTF-8 request body limit: 4096 bytes.
Schema: SignupInput
| Field | Required | Type | Meaning and constraints |
|---|
Unknown fields are rejected.
curl example
Replace resource-ID placeholders with returned IDs.
Save the intended payload as a private request.json file and replace illustrative values. For an uncertain response, follow the operation-specific recovery rules.
{}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/signups" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 202
Request accepted; inspect the response for its meaning.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"status": "awaiting_human",
"approval_url": "https://cherami.to/claim",
"message": "Example"
}HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_request: Signup or claim contains unsupported fields. Signup accepts only an empty object.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 403
origin_not_allowed: Signup/claim requests with an Origin header must use Cherami's origin. Use the hosted Claim page for human approval.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the endpoint's body limit.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 429
rate_limited: Signup discovery or claim attempts exceeded their limit. Respect Retry-After.
X-Request-ID: Support correlation ID, not an idempotency key.Retry-After: Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit.
Content type: application/json.
HTTP 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: SignupResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
status | Yes | "awaiting_human" | |
approval_url | Yes | "https://cherami.to/claim" | |
message | Yes | string |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1