openapi: 3.1.0
info:
  title: Clawvisor Gateway Auth Tasks 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: Tasks
  description: Declare, approve, expand, and complete task scopes.
paths:
  /api/tasks:
    post:
      operationId: createTask
      tags:
      - Tasks
      summary: Declare a task scope
      description: Declare a purpose and the authorized service/action pairs the agent needs. The task starts as `pending_approval`; the user approves the scope via dashboard, Telegram, or a mobile push. Use `?wait=true` to block until the user approves or denies in a single round-trip.
      parameters:
      - name: wait
        in: query
        required: false
        description: Long-poll until the task is approved or denied.
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Task created (and resolved when wait=true).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          description: Missing or invalid agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listTasks
      tags:
      - Tasks
      summary: List tasks
      description: List the agent's active, standing, pending, and completed tasks.
      responses:
        '200':
          description: A list of tasks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
  /api/tasks/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getTask
      tags:
      - Tasks
      summary: Get a task (supports long-polling)
      description: Retrieve a task's current state. Use `?wait=true` to long-poll until the status changes to `active` or `denied`.
      parameters:
      - name: wait
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/tasks/{id}/expand:
    post:
      operationId: expandTask
      tags:
      - Tasks
      summary: Request a scope expansion
      description: Add an action not in the original task scope. The user is notified and can approve or deny; on approval the action is added and the session task TTL is reset. Standing tasks cannot be expanded.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizedAction'
      responses:
        '200':
          description: Expansion requested / resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /api/tasks/{id}/complete:
    post:
      operationId: completeTask
      tags:
      - Tasks
      summary: Mark a task complete
      description: Signal the task is done; chain-context facts are cleaned up.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Task completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
components:
  schemas:
    AuthorizedAction:
      type: object
      required:
      - service
      - action
      properties:
        service:
          type: string
          description: Service (optionally with account alias), e.g. `google.gmail:user@example.com`.
        action:
          type: string
          description: Action on the service, e.g. `list_messages`, `send_message`.
        auto_execute:
          type: boolean
          description: When true, in-scope requests run immediately; false requires per-request approval.
        expected_use:
          type: string
          description: Per-action description checked against actual request params by intent verification.
        verification:
          type: string
          enum:
          - strict
          - lenient
          - false
          description: Per-scope intent verification mode.
    Task:
      type: object
      properties:
        id:
          type: string
        purpose:
          type: string
        status:
          type: string
          enum:
          - pending_approval
          - active
          - pending_scope_expansion
          - completed
          - denied
          - expired
          - revoked
        lifetime:
          type: string
          enum:
          - session
          - standing
          - sliding
        authorized_actions:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizedAction'
        expires_at:
          type: string
          format: date-time
    PlannedCall:
      type: object
      required:
      - service
      - action
      - params
      properties:
        service:
          type: string
        action:
          type: string
        params:
          type: object
          additionalProperties: true
          description: Known params, or `$chain` for values that come from a prior call's results.
        reason:
          type: string
    Error:
      type: object
      properties:
        status:
          type: string
        error:
          type: string
        code:
          type: string
    TaskCreate:
      type: object
      required:
      - purpose
      - authorized_actions
      properties:
        purpose:
          type: string
          description: Capability statement shown at approval and checked by intent verification.
        authorized_actions:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizedAction'
        planned_calls:
          type: array
          items:
            $ref: '#/components/schemas/PlannedCall'
        lifetime:
          type: string
          enum:
          - session
          - standing
          - sliding
          description: session (default, TTL), standing (until revoked), or sliding (auto-extends on use).
        expires_in_seconds:
          type: integer
          description: Task TTL for session tasks.
        callback_url:
          type: string
          format: uri
          description: URL Clawvisor POSTs a task callback to on approval/denial/expansion/expiry.
  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.