openapi: 3.1.0
info:
  title: Clawvisor Auth Gateway API
  version: 0.2.0
  description: The Clawvisor gateway API — the authorization layer AI agents call to act on external services (Gmail, Calendar, Drive, Contacts, GitHub, Slack, Notion, Linear, Stripe, Twilio, iMessage) without ever holding the underlying credentials. Agents declare a **task** describing their purpose and the service/action pairs they need; the user approves the scope once; and every subsequent gateway request is checked against restrictions, task scope, intent verification, and (optionally) per-request human approval before Clawvisor injects credentials, executes through an adapter, and returns a clean semantic result. This description is GENERATED by the API Evangelist enrichment pipeline from Clawvisor's public README and agent protocol (skills/clawvisor/SKILL.md.tmpl); Clawvisor does not publish an OpenAPI document. Every path, method, field, and status below is documented in github.com/clawvisor/clawvisor.
  x-generated-by: api-evangelist-enrichment-pipeline
  x-source: https://github.com/clawvisor/clawvisor/blob/main/README.md
  license:
    name: MIT
    url: https://github.com/clawvisor/clawvisor/blob/main/LICENSE
  contact:
    name: Clawvisor
    url: https://clawvisor.com
servers:
- url: https://app.clawvisor.com
  description: Hosted Clawvisor (managed service)
- url: http://localhost:25297
  description: Self-hosted local daemon (default port)
security:
- agentToken: []
tags:
- name: Gateway
  description: Execute authorized actions on downstream services through the gateway.
paths:
  /api/gateway/request:
    post:
      operationId: gatewayRequest
      tags:
      - Gateway
      summary: Execute an authorized action
      description: Execute a single action on a downstream service under an approved task. Clawvisor checks restrictions, validates the action against task scope and intent verification, injects credentials, executes through the service adapter, and returns a semantic result. Requests without a `task_id` fall back to per-request approval. Use `?wait=true` to block until a pending request resolves.
      parameters:
      - name: wait
        in: query
        required: false
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayRequest'
      responses:
        '200':
          description: Gateway result (see status field).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
        '401':
          description: Missing or invalid agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/gateway/request/{request_id}/execute:
    post:
      operationId: executeGatewayRequest
      tags:
      - Gateway
      summary: Execute a previously approved pending request
      description: Execute a gateway request that was left `pending` for human approval, once the user has approved it. Idempotent on `request_id`.
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Gateway result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
components:
  schemas:
    GatewayRequest:
      type: object
      required:
      - service
      - action
      properties:
        service:
          type: string
        action:
          type: string
        params:
          type: object
          additionalProperties: true
        reason:
          type: string
          description: Why the agent is making this request (checked by intent verification).
        request_id:
          type: string
          description: Client-supplied correlation id; used for callbacks and the /execute follow-up.
        task_id:
          type: string
          description: The approved task this request runs under. Omit for per-request approval.
        session_id:
          type: string
          description: Required on standing tasks; scopes chain-context verification to one invocation.
        context:
          type: object
          properties:
            source:
              type: string
            callback_url:
              type: string
              format: uri
    GatewayResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - executed
          - pending
          - blocked
          - restricted
          - pending_task_approval
          - pending_scope_expansion
          - task_expired
          - error
        result:
          type: object
          properties:
            summary:
              type: string
            data: {}
        audit_id:
          type: string
        error:
          type: string
        code:
          type: string
          description: Machine error code, e.g. SERVICE_NOT_CONFIGURED, MISSING_SESSION_ID.
    Error:
      type: object
      properties:
        status:
          type: string
        error:
          type: string
        code:
          type: string
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: Agent token (or dashboard JWT for admin-gated endpoints), sent as Authorization Bearer header.
    agentTokenHeader:
      type: apiKey
      in: header
      name: X-Clawvisor-Agent-Token
      description: Agent token for the skill catalog endpoint.