# Redeem a claim phrase POST /v1/claims Source: https://cherami.to/docs/api/access/redeem-claim {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `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](https://cherami.to/docs/guides/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](https://cherami.to/docs/api/errors#error-codes). ### Optional signup research [#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](https://cherami.to/privacy) ## Request body [#request-body] JSON object. Total UTF-8 request body limit: 4096 bytes. ### Schema: ClaimInput [#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 [#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](https://cherami.to/docs/api/errors#retry-by-operation). ```json { "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. ```sh 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.json ``` ## Responses [#responses] ### HTTP 201 [#http-201] Successful operation; inspect resource state and outcome fields. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [ClaimResult](#schema-claimresult) ### HTTP 400 [#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`. [Error](#schema-error) ### HTTP 403 [#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`. [Error](#schema-error) ### HTTP 413 [#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`. [Error](#schema-error) ### HTTP 415 [#http-415] `unsupported_media_type`: Send `Content-Type: application/json`. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 429 [#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`. [Error](#schema-error) ### HTTP 500 [#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`. [Error](#schema-error) ## Schema: ClaimResult [#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 [#schema-error] | Field | Required | Type | Meaning and constraints | | ------- | -------- | ------ | ----------------------- | | `error` | Yes | object | | ### `error` fields [#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](https://cherami.to/docs/api/errors) ยท [Download OpenAPI 3.1](https://cherami.to/openapi.json)