OpenAPI

openapi: 3.1.0
info:
  title: TXT CLAW API
  version: v1
  description: |
    TXT CLAW developer API (preview).

    Create a dedicated OpenClaw agent and talk to it over HTTPS.
    SMS provisioning is a separate/optional lane.
servers:
  - url: https://txtclaw-sms-e2e.lopez731.workers.dev
    description: Preview (Workers)
security:
  - bearerAuth: []
paths:
  /v1/status:
    get:
      summary: Status
      operationId: getStatus
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/warmup:
    post:
      summary: Warm up gateway
      operationId: postWarmup
      description: |
        Starts the TXT CLAW gateway so the first agent reply is faster.
        Default mode is hosted. BYOK warmup requires a dashboard-issued key with BYOK configured.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarmupRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WarmupResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden (requires dashboard-issued key for BYOK mode)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflict (BYOK not configured)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: BYOK not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/byok:
    get:
      summary: Get BYOK metadata
      operationId: getByok
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetByokResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden (requires dashboard-issued key)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      summary: Set BYOK (encrypted at rest)
      operationId: putByok
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutByokRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PutByokResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden (requires dashboard-issued key)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: BYOK not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      summary: Clear BYOK
      operationId: deleteByok
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteByokResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden (requires dashboard-issued key)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agents:
    post:
      summary: Create agent
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentRequest"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAgentResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agents/{agent_id}:
    get:
      summary: Get agent
      operationId: getAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAgentResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agents/{agent_id}/messages:
    post:
      summary: Send message
      operationId: sendMessage
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendMessageRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendMessageResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agents/{agent_id}/channels/sms:
    post:
      summary: Enable SMS (scaffold)
      operationId: enableSms
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnableSmsRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnableSmsResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds until retry is allowed.
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: TXTCLAW_API_KEY
  schemas:
    ErrorResponse:
      type: object
      description: Error response. Always include `trace_id` when reporting issues.
      additionalProperties: true
      properties:
        error: { type: string }
        trace_id: { type: string }
        limit_key: { type: string }
        reason: { type: string }
      required: [error]

    StatusResponse:
      type: object
      additionalProperties: false
      properties:
        ok: { type: boolean }
        service: { type: string }
        version: { type: string }
        mode: { type: string }
        trace_id: { type: string }
      required: [ok, service, version, mode, trace_id]

    WarmupRequest:
      type: object
      additionalProperties: false
      properties:
        mode:
          type: string
          enum: [hosted, byok]
          description: Warm the hosted gateway (default) or the BYOK gateway (requires BYOK configured).

    WarmupResponse:
      type: object
      additionalProperties: false
      properties:
        ok: { type: boolean }
        warmed: { type: boolean }
        mode: { type: string, enum: [hosted, byok] }
        trace_id: { type: string }
      required: [ok, warmed, mode, trace_id]

    CreateAgentRequest:
      type: object
      additionalProperties: false
      properties:
        system_prompt:
          type: string
          description: System prompt applied to the agent.
          maxLength: 2000
        customer_ref:
          type: string
          description: Your internal customer identifier (optional).
          maxLength: 200
        metadata:
          type: object
          description: Opaque metadata (optional). JSON string length is capped in preview.
          additionalProperties: true
        sms:
          type: object
          additionalProperties: false
          properties:
            mode:
              type: string
              enum: [none, sandbox, managed, byo_twilio]
          required: [mode]
        llm:
          type: object
          additionalProperties: false
          description: |
            Optional LLM configuration (hosted router by default).

            For BYOK, you can either:
            - set BYOK once via `PUT /v1/byok` and then create agents with `llm.mode="byok"`, or
            - provide `llm.api_key` at agent creation time (rate limited).
          properties:
            mode:
              type: string
              enum: [hosted, byok]
              description: "hosted (default) or byok"
            tier:
              type: string
              enum: [fast, smart]
              description: "fast (default) or smart (may use fallback model)"
            model:
              type: string
              description: "Optional explicit model override"
              maxLength: 200
            provider:
              type: string
              enum: [openai_compat, openai, anthropic]
              description: "BYOK provider (required if you set llm.api_key)"
            base_url:
              type: string
              description: "Optional provider base URL (e.g. gateways)"
              maxLength: 400
            api_key:
              type: string
              description: "Optional BYOK provider key (recommended: set once via PUT /v1/byok)"
            label:
              type: string
              description: "Optional label for your BYOK config"
              maxLength: 60
      required: []

    ByokProvider:
      type: string
      enum: [openai_compat, openai, anthropic]

    ByokConfig:
      type: object
      additionalProperties: false
      properties:
        provider:
          $ref: "#/components/schemas/ByokProvider"
        base_url:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        fingerprint:
          type: string
          description: "Non-reversible fingerprint for debugging/UI"
        updated_at:
          type: string
      required: [provider, fingerprint, updated_at]

    GetByokResponse:
      type: object
      additionalProperties: false
      properties:
        ok: { type: boolean }
        byok:
          oneOf:
            - $ref: "#/components/schemas/ByokConfig"
            - type: "null"
        trace_id: { type: string }
      required: [ok, byok, trace_id]

    PutByokRequest:
      type: object
      additionalProperties: false
      properties:
        provider:
          $ref: "#/components/schemas/ByokProvider"
        api_key:
          type: string
        base_url:
          type: string
          description: "Optional provider base URL (e.g. gateways)"
        model:
          type: string
          description: "Optional model override"
        label:
          type: string
          description: "Optional label"
      required: [provider, api_key]

    PutByokResponse:
      type: object
      additionalProperties: false
      properties:
        ok: { type: boolean }
        byok:
          $ref: "#/components/schemas/ByokConfig"
        trace_id: { type: string }
      required: [ok, byok, trace_id]

    DeleteByokResponse:
      type: object
      additionalProperties: false
      properties:
        ok: { type: boolean }
        trace_id: { type: string }
      required: [ok, trace_id]

    CreateAgentResponse:
      type: object
      additionalProperties: false
      properties:
        agent_id: { type: string }
        status: { type: string, enum: [active] }
        sms:
          type: object
          additionalProperties: false
          properties:
            status:
              type: string
              enum: [disabled, needs_compliance, pending, active, needs_setup]
          required: [status]
        trace_id: { type: string }
      required: [agent_id, status, trace_id]

    GetAgentResponse:
      type: object
      additionalProperties: false
      properties:
        agent_id: { type: string }
        status: { type: string }
        created_at: { type: string }
        updated_at: { type: string }
        sms:
          type: object
          additionalProperties: false
          properties:
            status: { type: string }
            phone_number: { type: string }
          required: [status]
        trace_id: { type: string }
      required: [agent_id, status, created_at, updated_at, trace_id]

    SendMessageRequest:
      type: object
      additionalProperties: false
      properties:
        text:
          type: string
          maxLength: 4000
        user_ref:
          type: string
          description: Optional user identifier (reserved for future multi-user routing).
      required: [text]

    SendMessageResponse:
      type: object
      additionalProperties: false
      properties:
        reply_text: { type: string }
        warnings:
          type: array
          items: { type: string }
        trace_id: { type: string }
      required: [reply_text, trace_id]

    EnableSmsRequest:
      type: object
      additionalProperties: false
      properties:
        mode:
          type: string
          enum: [sandbox, managed, byo_twilio]
      required: [mode]

    EnableSmsResponse:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum: [disabled, needs_compliance, pending, active, needs_setup]
        trace_id: { type: string }
      required: [status, trace_id]