ASAP Copilot API

openapi: 3.2.0
info:
  title: ASAP Platform Copilot API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: Copilot
  description: 'Internal invoice copilot: streaming turns (SSE) with auto-executed reads/drafts and confirmation-gated regulated actions.'
paths:
  /v1/copilot/messages:
    post:
      tags:
      - Copilot
      summary: Stream one copilot turn over Server-Sent Events
      description: 'Emits `delta` (text fragments), `tool_result` (auto-executed tools),

        `proposal` (a gated tool staged for confirmation), `error` (a transport

        failure), and a terminal `done` event.'
      operationId: stream_message
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamMessageRequest'
        required: true
      responses:
        '200':
          description: SSE stream of copilot events (delta, tool_result, proposal, done, error)
        '401':
          description: No authenticated org context
        '402':
          description: 'The `copilot` app requires a higher plan (Solo or above): `plan_required`.'
        '403':
          description: Caller has no membership in the active org
        '404':
          description: 'The `copilot` app is not activated for this organisation: `app_not_available`.'
  /v1/copilot/proposals/{id}/confirm:
    post:
      tags:
      - Copilot
      summary: Confirm and execute a staged action proposal
      description: 'Atomically consumes the pending proposal (single-use) and replays its

        **persisted** arguments under a confirmed dispatch context — the client body

        is never trusted for the action arguments.'
      operationId: confirm_proposal
      parameters:
      - name: id
        in: path
        description: Proposal id to confirm
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Tool executed (wrapped in the `{data}` envelope)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmProposalResponse'
        '402':
          description: 'The `copilot` app requires a higher plan (Solo or above): `plan_required`.'
        '403':
          description: Caller is not an interactive user or lacks the tool scope
        '404':
          description: 'The `copilot` app is not activated for this organisation: `app_not_available`.'
        '409':
          description: Proposal is not pending (already confirmed, expired, or unknown)
        '422':
          description: Invalid arguments or tool failure
components:
  schemas:
    StreamMessageRequest:
      type: object
      description: 'Request body for `POST /v1/copilot/messages`.


        The client owns the conversation: it replays the full running history each

        turn (there is no server-side conversation store in V3).'
      required:
      - messages
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/CopilotMessage'
          description: Conversation so far, oldest first.
    ConfirmProposalResponse:
      type: object
      description: Response body for `POST /v1/copilot/proposals/{id}/confirm`.
      required:
      - tool
      - result
      properties:
        result:
          description: Free-form JSON outcome of the tool execution.
        tool:
          type: string
          description: Wire name of the tool that ran.
    CopilotMessage:
      type: object
      description: One conversation turn supplied by the client.
      required:
      - role
      - content
      properties:
        content:
          type: string
          description: Plain-text body of the turn.
        role:
          type: string
          description: Author of the turn (`user` or `assistant`).
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session