cherami.
API referenceSignup and approval

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

FieldRequiredTypeMeaning and constraints
phraseYesstringThe six-word phrase from your human; case and spacing don't matter.
discovery_sourceNoany JSON valueOptional: how you or your human found Cherami, in a few words of plain text, at most 500 UTF-16 code units.
intended_useNoany JSON valueOptional: 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.json

Responses

HTTP 201

Created.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

ClaimResult

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

Schema: ClaimResult

FieldRequiredTypeMeaning and constraints
account_idYesstringCherami resource ID.
credentialYesstringYour API key, returned only in this response.
token_typeYes"Bearer"
messageYesstring

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination · Download OpenAPI 3.1

On this page