Ausca Invocations 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 Invocations 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: Invocations
paths:
  /v1/invocations/prepare:
    post:
      description: Validate one exact invocation envelope and return immutable preparation terms or a typed refusal. Preparation never accepts payment material from model-authored tool arguments.
      operationId: PrepareInvocation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareInvocationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrepareInvocationResult'
          description: Prepared terms or a semantic refusal
        default:
          $ref: '#/components/responses/ErrorResponse'
      security: []
      summary: Validate invocation input and return binding terms
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/PrepareInvocationRequest'
        name: ausca_prepare_invocation
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/PrepareInvocationResult'
      tags:
      - Invocations
  /v1/invocations/{invocation_id}:
    get:
      description: Read the authoritative durable state, output commitment, and receipt reference for one invocation without creating a new purchase or retry identity.
      operationId: GetInvocation
      parameters:
      - $ref: '#/components/parameters/InvocationID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvocationResult'
          description: Invocation state
        default:
          $ref: '#/components/responses/ErrorResponse'
      security: []
      summary: Read authoritative invocation state
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/GetInvocationInput'
        name: ausca_get_invocation
        openWorld: false
        readOnly: true
        resultSchema: '#/components/schemas/GetInvocationResult'
      tags:
      - Invocations
  /v1/invocations/{invocation_id}/cancel:
    post:
      description: Request bounded cancellation of one invocation. Cancellation is idempotent, may be refused, and may lose a race with terminal completion.
      operationId: CancelInvocation
      parameters:
      - $ref: '#/components/parameters/InvocationID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelInvocationResult'
          description: Cancellation result
        default:
          $ref: '#/components/responses/ErrorResponse'
      security: []
      summary: Request bounded cancellation
      x-ausca-mcp:
        destructive: true
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/CancelInvocationInput'
        name: ausca_cancel_invocation
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/CancelInvocationResult'
      tags:
      - Invocations
components:
  schemas:
    ArtifactUri:
      description: Opaque artifact reference minted by artifact commitment. Relay it unchanged; its form is not part of the contract.
      maxLength: 512
      minLength: 1
      type: string
    InvocationFailure:
      additionalProperties: false
      properties:
        code:
          maxLength: 96
          minLength: 1
          type: string
        message:
          maxLength: 500
          minLength: 1
          type: string
      required:
      - code
      - message
      type: object
    Digest:
      pattern: ^sha256:[a-f0-9]{64}$
      type: string
    InvocationState:
      additionalProperties: false
      properties:
        failure:
          $ref: '#/components/schemas/InvocationFailure'
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        offer_revision_digest:
          $ref: '#/components/schemas/Digest'
        output: {}
        output_artifact:
          $ref: '#/components/schemas/ArtifactEvidence'
        output_digest:
          $ref: '#/components/schemas/Digest'
        receipt_ref:
          $ref: '#/components/schemas/ReceiptReference'
        state:
          enum:
          - admitted
          - running
          - succeeded
          - failed
          - cancellation_requested
          - cancelled
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - invocation_id
      - offer_revision_digest
      - state
      - updated_at
      type: object
    ReceiptReference:
      additionalProperties: false
      properties:
        public_url:
          description: Unguessable public verification page for the privacy-bounded hash-only proof. It reveals the receipt digest, service, public price, and completion time, but not input bytes, output bytes, or their content digests.
          format: uri
          maxLength: 2048
          pattern: ^https://[^?#]+/r/[a-f0-9]{64}$
          type: string
        type:
          const: receipt
        uri:
          description: Opaque receipt identity minted by the notary. Relay it unchanged; its form is not part of the contract.
          maxLength: 512
          minLength: 1
          type: string
      required:
      - type
      - uri
      type: object
    GetInvocationResult:
      oneOf:
      - additionalProperties: false
        properties:
          invocation:
            $ref: '#/components/schemas/InvocationState'
          status:
            const: ok
        required:
        - status
        - invocation
        type: object
      - $ref: '#/components/schemas/RefusedResult'
    Identifier:
      maxLength: 128
      minLength: 1
      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
      type: string
    RefusedResult:
      additionalProperties: false
      properties:
        code:
          enum:
          - offer_unavailable
          - schema_mismatch
          - quote_expired
          - terms_changed
          - replay_conflict
          - payment_authority_required
          - payment_not_authorized
          - capacity_unavailable
          - not_found
          - cancellation_not_available
          - artifact_gone
          type: string
        reason:
          maxLength: 512
          minLength: 1
          type: string
        status:
          const: refused
      required:
      - status
      - code
      - reason
      type: object
    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
    ArtifactEvidence:
      additionalProperties: false
      properties:
        artifact_uri:
          $ref: '#/components/schemas/ArtifactUri'
        content_digest:
          $ref: '#/components/schemas/Digest'
        created_at:
          format: date-time
          type: string
        media_type:
          maxLength: 200
          minLength: 1
          type: string
        size_bytes:
          maximum: 26214400
          minimum: 1
          type: integer
      required:
      - artifact_uri
      - content_digest
      - media_type
      - size_bytes
      - created_at
      type: object
    PrepareInvocationResult:
      oneOf:
      - $ref: '#/components/schemas/PreparedInvocation'
      - $ref: '#/components/schemas/RefusedResult'
    CancelInvocationResult:
      oneOf:
      - additionalProperties: false
        properties:
          invocation:
            $ref: '#/components/schemas/InvocationState'
          status:
            enum:
            - cancellation_requested
            type: string
        required:
        - status
        - invocation
        type: object
      - $ref: '#/components/schemas/RefusedResult'
    PreparedInvocation:
      additionalProperties: false
      properties:
        challenge:
          $ref: '#/components/schemas/PaymentChallenge'
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        status:
          const: prepared
      required:
      - status
      - invocation_id
      - challenge
      type: object
    InvocationEnvelope:
      additionalProperties: false
      properties:
        idempotency_key:
          maxLength: 128
          minLength: 16
          type: string
        input: {}
        input_schema_digest:
          $ref: '#/components/schemas/Digest'
        offer_id:
          $ref: '#/components/schemas/Identifier'
        offer_revision:
          $ref: '#/components/schemas/Identifier'
        offer_revision_digest:
          $ref: '#/components/schemas/Digest'
        output_schema_digest:
          $ref: '#/components/schemas/Digest'
      required:
      - offer_id
      - offer_revision
      - offer_revision_digest
      - input_schema_digest
      - output_schema_digest
      - input
      - idempotency_key
      type: object
    PaymentChallenge:
      additionalProperties: false
      properties:
        media_type:
          maxLength: 128
          minLength: 1
          type: string
        payload: {}
        payload_digest:
          $ref: '#/components/schemas/Digest'
        protocol_version:
          maxLength: 32
          minLength: 1
          type: string
        quote_expires_at:
          format: date-time
          type: string
        quote_ref:
          $ref: '#/components/schemas/Identifier'
        settlement_family:
          maxLength: 64
          minLength: 1
          type: string
      required:
      - settlement_family
      - protocol_version
      - media_type
      - payload
      - payload_digest
      - quote_ref
      - quote_expires_at
      type: object
    PrepareInvocationRequest:
      $ref: '#/components/schemas/InvocationEnvelope'
  parameters:
    InvocationID:
      in: path
      name: invocation_id
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
  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