chatrail-dev Workspace API

openapi: 3.2.0
info:
  title: ChatRail Workspace API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Workspace
  description: Identity, credentials, plan and usage.
paths:
  /v1/whoami:
    get:
      summary: Confirm a credential
      description: Shows exactly what the presented credential can do. The first call to make.
      tags:
      - Workspace
      operationId: get_v1_whoami
      responses:
        '200':
          description: The principal, its scopes and its workspace.
      security:
      - apiKey: []
  /v1/workspace:
    get:
      summary: Get the current workspace
      description: Includes the plan and what has been used against it.
      tags:
      - Workspace
      operationId: get_v1_workspace
      responses:
        '200':
          description: The workspace, the caller role and the plan.
      security:
      - session: []
    patch:
      summary: Rename the workspace
      description: Changes the display name shown to members, on invitations and in emails. The slug does not change. Needs `workspace:update`.
      tags:
      - Workspace
      operationId: patch_v1_workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
              - name
              additionalProperties: false
            example:
              name: Kettle & Co
      responses:
        '200':
          description: The workspace id, slug and new name.
        '400':
          description: The name is empty or longer than 80 characters.
      security:
      - session: []
  /v1/usage:
    get:
      summary: Usage counts
      description: Counts only. A count of messages is not a message; no content is reachable here.
      tags:
      - Workspace
      operationId: get_v1_usage
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 365
      responses:
        '200':
          description: Aggregated counts for the workspace.
      security:
      - apiKey:
        - usage:read
      - session: []
      x-scopes:
      - usage:read
  /v1/api-keys:
    post:
      summary: Issue an API key
      description: Returns the key **exactly once**. It is stored only as a hash and cannot be recovered. A key may never hold more than the person issuing it.
      tags:
      - Workspace
      operationId: post_v1_api-keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                scopes:
                  minItems: 1
                  type: array
                  items:
                    type: string
                    enum:
                    - messages:read
                    - messages:write
                    - connections:read
                    - connections:write
                    - webhooks:read
                    - webhooks:write
                    - schedules:read
                    - schedules:write
                    - ai:read
                    - ai:write
                    - mcp:read
                    - mcp:write
                    - usage:read
                environment:
                  default: live
                  type: string
                  enum:
                  - live
                  - test
              required:
              - name
              - scopes
              additionalProperties: false
            example:
              name: Order service
              scopes:
              - messages:write
              - messages:read
              environment: live
      responses:
        '201':
          description: The key, once.
        '403':
          description: Your role cannot grant those scopes.
      security:
      - session: []
    get:
      summary: List API keys
      tags:
      - Workspace
      operationId: get_v1_api-keys
      responses:
        '200':
          description: Key metadata and prefixes, never the keys.
      security:
      - session: []
  /v1/api-keys/{id}/revoke:
    post:
      summary: Revoke an API key
      tags:
      - Workspace
      operationId: post_v1_api-keys__id__revoke
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Key id.
      responses:
        '200':
          description: Revoked, immediately.
        '404':
          description: No such key.
      security:
      - session: []
  /v1/api-keys/{id}/rotate:
    post:
      summary: Rotate an API key
      description: Issues a replacement and revokes the old one.
      tags:
      - Workspace
      operationId: post_v1_api-keys__id__rotate
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Key id.
      responses:
        '200':
          description: The new key, once.
        '404':
          description: No such key.
      security:
      - session: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.