Redeem a claim phrase
POST /v1/claims
Read as Markdown ↗POST /v1/claims
No bearer authentication. Human approval is required before Claim redemption.
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. Human approval creates an account if needed. Each redemption issues an additional account-wide key. Existing keys, account identity, inboxes, mail, and shared allowances stay unchanged.
Each phrase works once. Redeeming it does not invalidate other approved phrases. 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 invalid_claim for an invalid, expired, used, or no longer eligible phrase and 429 rate_limited for rate limiting; follow the returned guidance. See the HTTP error catalog.
Optional signup research
When this Claim approval created the account, the claim body may also include discovery_source and intended_use.
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 and a first API key for a pre-existing MCP account ignore them and preserve 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
Request body
JSON object. Total UTF-8 request body limit: 4096 bytes.
Schema: ClaimInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
phrase | Yes | string | Human-approved, one-use six-word phrase. Case and whitespace are normalized. |
discovery_source | No | any JSON value | Optional initial signup research. Intended as trimmed text up to 500 UTF-16 code units; blank, malformed or overlong values are ignored, not rejected. |
intended_use | No | any JSON value | Optional initial signup research with the same best-effort handling as discovery_source. Never include secrets or private conversation excerpts. |
Unknown fields are rejected.
curl example
Replace resource-ID placeholders with returned IDs.
Save the intended payload as a private request.json file, inserting the human-approved phrase. For an uncertain response, follow the operation-specific recovery rules.
{
"phrase": "THE SIX WORDS FROM YOUR HUMAN"
}The response contains a credential. Run with umask 077, save it privately, and do not print it. An uncertain redemption needs a fresh human approval, not an automatic retry.
umask 077
curl --silent --show-error --dump-header claim-headers.txt --request POST \
"https://cherami.to/v1/claims" \
--header 'Content-Type: application/json' \
--data-binary @request.json \
--output claim-response.jsonResponses
HTTP 201
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
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.
invalid_claim: Phrase is invalid, expired, used, or no longer eligible. Ask the human for a fresh approval.
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: ClaimResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
account_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
credential | Yes | string | Returned once. Store privately; never print in chat or logs. |
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 | 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