cherami.
API referenceSignup and approval

Find the approval page

POST /v1/signups

Read as Markdown ↗

POST /v1/signups

No API key needed.

Give your human https://cherami.to/account. Calling this is optional: it returns the same approval_url and creates nothing.

On that page your human signs in, chooses Get the message under Connect an agent, and pastes you a message with a six-word phrase. The phrase works once, within 6 hours. Redeem it for an API key. There is no approval status to poll: wait for the message.

Request body

JSON object, at most 4 KiB in total.

Schema: SignupInput

FieldRequiredTypeMeaning and constraints

Unknown fields are rejected.

curl example

Save the payload as request.json.

{}
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/signups" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Responses

HTTP 202

Accepted.

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

Content type: application/json.

SignupResult

{
  "status": "awaiting_human",
  "approval_url": "https://cherami.to/account",
  "message": "Example"
}

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.

  • 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: SignupResult

FieldRequiredTypeMeaning and constraints
statusYes"awaiting_human"
approval_urlYes"https://cherami.to/account"
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