Redeem an approval phrase
POST /v1/claims
Read as Markdown ↗POST /v1/claims
No API key needed.
Send the six-word phrase your human gave you. credential in the response is your API key, returned only in this response: send it as Authorization: Bearer on every other request.
A phrase works once. If you lose the credential or the response, ask your human for a new approval (recovery).
The key can use every inbox and all mail on the account. It creates no inbox: list inboxes and use one that fits, or create one.
Optional signup questions
When you can answer from what you already know, add discovery_source (how you or your human found Cherami) and intended_use (what the account's inboxes are for), each a few words of plain text. Omit a question rather than guess or ask your human. Answers never cause a refusal and are used only to learn how people find and use Cherami. Privacy
Request body
JSON object, at most 4 KiB in total.
Schema: ClaimInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
phrase | Yes | string | The six-word phrase from your human; case and spacing don't matter. |
discovery_source | No | any JSON value | Optional: how you or your human found Cherami, in a few words of plain text, at most 500 UTF-16 code units. |
intended_use | No | any JSON value | Optional: what the account's inboxes are for, in a few words of plain text, at most 500 UTF-16 code units. |
Unknown fields are rejected.
curl example
Save the payload as request.json, with the phrase your human gave you.
{
"phrase": "THE SIX WORDS FROM YOUR HUMAN"
}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/claims" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 201
Created.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_request: The signup or redemption body has an unsupported field. Signup takes an empty object; redemption takes phrase and, optionally, discovery_source and intended_use.
invalid_claim: The phrase is invalid, expired or already used. Ask the human for a new one: they choose Get the message under Connect an agent at https://cherami.to/account.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 403
origin_not_allowed: Signup and redemption refuse requests carrying another site's Origin header. Call them from the agent's runtime, not from a web page.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the operation's body limit.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 429
rate_limited: Too many signup or redemption requests from this network. Wait for Retry-After, then try again.
X-Request-ID: Identifies this request; include it when reporting a problem.Retry-After: Seconds to wait before retrying. For sending allowance it matches sufficient_capacity_at.
Content type: application/json.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: ClaimResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
account_id | Yes | string | Cherami resource ID. |
credential | Yes | string | Your API key, returned only in this response. |
token_type | Yes | "Bearer" | |
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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |