Cherami Access API

openapi: 3.2.0
info:
  title: Cherami To Access API
  version: 1.0.0
  contact:
    name: Cherami
    email: hello@cherami.to
  description: 'Operations tagged access across 2 of this provider''s published API definitions: cherami-to-openapi.json, cherami-to-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cherami.to
security:
- apiKey: []
tags:
- name: Access
paths:
  /v1/signups:
    post:
      operationId: discoverSignup
      tags:
      - Access
      summary: Find the approval page
      description: '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.'
      parameters: []
      responses:
        '202':
          description: Accepted.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResult'
              example:
                status: awaiting_human
                approval_url: https://cherami.to/account
                message: Example
        '400':
          description: '`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`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`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.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`rate_limited`: Too many signup or redemption requests from this network. Wait for `Retry-After`, then try again.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying. For sending allowance it matches sufficient_capacity_at.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - origin_not_allowed
      - rate_limited
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - invalid_request
      - internal_error
      security: []
      requestBody:
        required: true
        description: JSON object, at most 4 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupInput'
            example: {}
      x-request-body-limit: 4096
      x-example-body: {}
    servers:
    - url: https://cherami.to
  /v1/claims:
    post:
      operationId: redeemClaim
      tags:
      - Access
      summary: Redeem an approval phrase
      description: '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'
      parameters: []
      responses:
        '201':
          description: Created.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResult'
        '400':
          description: '`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.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`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.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`rate_limited`: Too many signup or redemption requests from this network. Wait for `Retry-After`, then try again.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying. For sending allowance it matches sufficient_capacity_at.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - origin_not_allowed
      - rate_limited
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - invalid_request
      - invalid_claim
      - internal_error
      security: []
      requestBody:
        required: true
        description: JSON object, at most 4 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimInput'
            example:
              phrase: THE SIX WORDS FROM YOUR HUMAN
      x-request-body-limit: 4096
      x-example-body:
        phrase: THE SIX WORDS FROM YOUR HUMAN
    servers:
    - url: https://cherami.to
components:
  schemas:
    ClaimInput:
      type: object
      properties:
        phrase:
          type: string
          description: The six-word phrase from your human; case and spacing don't matter.
        discovery_source:
          description: 'Optional: how you or your human found Cherami, in a few words of plain text, at most 500 UTF-16 code units.'
        intended_use:
          description: 'Optional: what the account''s inboxes are for, in a few words of plain text, at most 500 UTF-16 code units.'
      required:
      - phrase
      additionalProperties: false
    SignupInput:
      type: object
      properties: {}
      required: []
      additionalProperties: false
    ClaimResult:
      type: object
      properties:
        account_id:
          type: string
          description: Cherami resource ID.
        credential:
          type: string
          description: Your API key, returned only in this response.
        token_type:
          const: Bearer
        message:
          type: string
      required:
      - account_id
      - credential
      - token_type
      - message
    SignupResult:
      type: object
      properties:
        status:
          const: awaiting_human
        approval_url:
          const: https://cherami.to/account
        message:
          type: string
      required:
      - status
      - approval_url
      - message
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Code to handle. Handle a code you don't recognize by its HTTP status.
            message:
              type: string
              description: Explanation of this case; its wording can change.
          required:
          - code
          - message
      required:
      - error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: Cherami API key
      description: Cherami API key (ch_...), from Account → API keys or from redeeming a human-approved phrase. Every key reaches all of the account's inboxes and mail. MCP OAuth tokens and browser sessions are not accepted.
x-refined-from:
- cherami-to-openapi.json
- cherami-to-openapi.yml