Ausca Browser Sessions API

openapi: 3.2.0
info:
  contact:
    name: Ausca
    url: https://ausca.com
  description: Transport-neutral paid invocations, keyless artifact ingress, and focused browser-session and receive-only inbox lease control.
  title: Ausca Browser Sessions API
  version: 1.3.1
  x-guidance: Start with https://ausca.com/SKILL.md, resolve an immutable offer before acting, and reuse the same invocation bytes and idempotency key after an uncertain response.
servers:
- url: https://ausca.com
security: []
tags:
- name: Browser Sessions
paths:
  /v1/browser-sessions/{session_id}:
    delete:
      description: Idempotently terminate the CDP relay and upstream browser for one lease. Closing never creates another payment. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: CloseBrowserSession
      parameters:
      - $ref: '#/components/parameters/BrowserSessionID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseBrowserSessionResult'
          description: Terminal browser-session view
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Close a browser-session lease
      x-ausca-mcp:
        destructive: true
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/BrowserSessionInput'
        name: ausca_browser_session_close
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/CloseBrowserSessionResult'
      tags:
      - Browser Sessions
    get:
      description: Return authoritative status and expiry for one browser-session lease. The lease capability is supplied by the transport and is never a tool argument or response field.
      operationId: GetBrowserSession
      parameters:
      - $ref: '#/components/parameters/BrowserSessionID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBrowserSessionResult'
          description: Authoritative browser-session view
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Read browser-session lease status
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/BrowserSessionInput'
        name: ausca_browser_session_status
        openWorld: false
        readOnly: true
        resultSchema: '#/components/schemas/GetBrowserSessionResult'
      tags:
      - Browser Sessions
  /v1/browser-sessions/{session_id}/connections:
    post:
      description: Return one single-use Ausca CDP relay URL for a ready lease. The URL expires after 60 seconds, only one CDP connection may be live, and no more than 64 unexpired tickets may coexist. Expired ticket records are compacted, so this is not a lifetime reconnect quota. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments. The upstream provider URL and credential are never disclosed.
      operationId: ConnectBrowserSession
      parameters:
      - $ref: '#/components/parameters/BrowserSessionID'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectBrowserSessionResult'
          description: Short-lived CDP relay connection
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Mint a browser CDP connection
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/ConnectBrowserSessionInput'
        name: ausca_browser_session_connect
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/ConnectBrowserSessionResult'
      tags:
      - Browser Sessions
components:
  parameters:
    IdempotencyKey:
      description: Stable retry identity for a ticket-minting operation.
      in: header
      name: Idempotency-Key
      required: true
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
    BrowserSessionID:
      in: path
      name: session_id
      required: true
      schema:
        $ref: '#/components/schemas/BrowserSessionID'
  schemas:
    BrowserSession:
      additionalProperties: false
      properties:
        closed_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        session_id:
          $ref: '#/components/schemas/BrowserSessionID'
        state:
          enum:
          - creating
          - ready
          - closing
          - closed
          - expired
          - failed
          type: string
      required:
      - session_id
      - state
      - created_at
      - expires_at
      type: object
    BrowserConnection:
      additionalProperties: false
      properties:
        expires_at:
          format: date-time
          type: string
        websocket_url:
          format: uri
          maxLength: 2048
          minLength: 1
          pattern: ^wss://browser\.ausca\.com/
          type: string
      required:
      - websocket_url
      - expires_at
      type: object
    IdempotencyKey:
      maxLength: 128
      minLength: 16
      pattern: ^[^\s\x00-\x1F\x7F](?:[^\x00-\x1F\x7F]*[^\s\x00-\x1F\x7F])?$
      type: string
    Identifier:
      maxLength: 128
      minLength: 1
      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
      type: string
    BrowserSessionID:
      pattern: ^brs_[A-Za-z0-9_-]{22,64}$
      type: string
    ErrorResult:
      additionalProperties: false
      properties:
        code:
          enum:
          - invalid_request
          - not_found
          - conflict
          - payment_required
          - unavailable
          - upstream_error
          - gone
          - rate_limited
          - attachment_blocked
          type: string
        inspect_url:
          description: Recovery status URL when payment settled but delivery failed.
          type: string
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        message:
          maxLength: 512
          minLength: 1
          type: string
        status:
          const: error
      required:
      - status
      - code
      - message
      type: object
    CloseBrowserSessionResult:
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/BrowserSession'
        status:
          enum:
          - closed
          - already_terminal
          type: string
      required:
      - status
      - session
      type: object
    GetBrowserSessionResult:
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/BrowserSession'
        status:
          const: ok
      required:
      - status
      - session
      type: object
    ConnectBrowserSessionResult:
      additionalProperties: false
      properties:
        connection:
          $ref: '#/components/schemas/BrowserConnection'
        status:
          const: ticket_issued
      required:
      - status
      - connection
      type: object
  responses:
    ErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
      description: Transport or infrastructure failure
  securitySchemes:
    LeaseCapability:
      bearerFormat: opaque
      description: Opaque expiry-bound authority for one Ausca resource lease. Never place it in JSON, query parameters, MCP tool arguments, logs, or receipts.
      scheme: bearer
      type: http
x-ausca-mcp-server:
  description: 'Agent infrastructure on demand: discover and control metered, keyless services with explicit pricing, bounded payment authority, and receipt-backed results.'
  icon:
    mimeType: image/svg+xml
    size: any
    src: https://ausca.com/favicon.svg
  instructions: 'Use search and get to resolve an immutable offer before acting. Paid tools take x402 v2 payment only in params._meta["x402/payment"], never in tool arguments: a call without it moves no money and returns the PaymentRequired as an isError result''s structuredContent; retry the same arguments with the signed PaymentPayload and read settlement evidence from result._meta["x402/payment-response"]. For an offer without a listed paid tool, follow the selected service SKILL.md and use its canonical HTTP invocation resource. Browser and inbox lifecycle tools take their lease bearer from the MCP HTTP request Authorization header, never from tool arguments.'
  name: ausca
  registry:
    description: Pay-per-call APIs and MCP services for agents, no accounts or keys, with verifiable receipts.
    name: com.ausca/agent-services
    package:
      argument: mcp
      identifier: ausca
      registryType: npm
      runtimeHint: npx
      version: 0.1.0
    version: 1.2.6
  title: Ausca