openapi: 3.1.1
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: Ausca Vendor API
  version: 1.0.1
  description: Six transport-neutral operations over immutable offer revisions.
  contact:
    name: Ausca
    url: https://ausca.com
  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: []
x-ausca-mcp-server:
  name: ausca
  title: Ausca
  description: "Agent infrastructure on demand: discover and control metered, keyless services with explicit pricing, bounded payment authority, and receipt-backed results."
  instructions: Use search and get to resolve an immutable offer before acting. The public MCP transport does not accept wallets or payment credentials and omits the disabled paid-invocation tool. Follow the selected service SKILL.md and use the canonical HTTP invocation resource for paid execution.
  icon:
    src: https://ausca.com/favicon.svg
    mimeType: image/svg+xml
    size: any
  registry:
    name: com.ausca/agent-services
    description: Pay-per-call APIs and MCP services for agents, no accounts or keys, with verifiable receipts.
paths:
  /v1/offers:
    get:
      operationId: SearchOffers
      summary: Search immutable offers
      description: Search the current immutable Ausca offer catalog by free-text query. Returns stable offer identities and revision digests without creating product or payment state.
      x-ausca-mcp:
        name: ausca_search_offers
        inputSchema: '#/components/schemas/SearchOffersInput'
        resultSchema: '#/components/schemas/SearchOffersResult'
        readOnly: true
        destructive: false
        idempotent: true
        openWorld: false
        enabledByDefault: true
      parameters:
        - name: q
          in: query
          schema:
            $ref: '#/components/schemas/SearchQuery'
        - name: limit
          in: query
          schema:
            $ref: '#/components/schemas/SearchLimit'
        - name: cursor
          in: query
          description: Opaque continuation returned by the preceding page for the same query and catalog snapshot.
          schema:
            $ref: '#/components/schemas/CatalogCursor'
      responses:
        '200':
          description: Matching offers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchOffersResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/offers/{offer_id}:
    get:
      operationId: GetOffer
      summary: Resolve an active or pinned offer revision
      description: Resolve one active offer or an exact immutable revision, including the schema and revision digests required to construct a valid invocation envelope.
      x-ausca-mcp:
        name: ausca_get_offer
        inputSchema: '#/components/schemas/GetOfferInput'
        resultSchema: '#/components/schemas/GetOfferResult'
        readOnly: true
        destructive: false
        idempotent: true
        openWorld: false
        enabledByDefault: true
      parameters:
        - $ref: '#/components/parameters/OfferID'
        - name: revision_digest
          in: query
          description: Optional immutable revision digest; absence resolves the active revision.
          schema:
            $ref: '#/components/schemas/Digest'
      responses:
        '200':
          description: Resolved offer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOfferResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/invocations/prepare:
    post:
      operationId: PrepareInvocation
      summary: Validate invocation input and return binding terms
      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.
      x-ausca-mcp:
        name: ausca_prepare_invocation
        inputSchema: '#/components/schemas/PrepareInvocationRequest'
        resultSchema: '#/components/schemas/PrepareInvocationResult'
        readOnly: false
        destructive: false
        idempotent: true
        openWorld: true
        enabledByDefault: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareInvocationRequest'
      responses:
        '200':
          description: Prepared terms or a semantic refusal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrepareInvocationResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/invocations:
    post:
      operationId: InvokeOffer
      summary: Admit or replay one invocation
      description: Admit or replay one idempotent paid invocation when settlement authority is supplied by the host boundary. The public MCP transport keeps this tool disabled; paid callers use the canonical HTTP resource.
      x-ausca-mcp:
        name: ausca_invoke_offer
        inputSchema: '#/components/schemas/InvokeOfferRequest'
        resultSchema: '#/components/schemas/InvokeOfferResult'
        readOnly: false
        destructive: true
        idempotent: true
        openWorld: true
        enabledByDefault: false
      parameters:
        - name: PAYMENT-SIGNATURE
          in: header
          required: false
          description: Standard-base64 encoded external x402 v2 PaymentPayload value
          schema:
            type: string
            minLength: 1
            maxLength: 65536
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeOfferRequest'
      responses:
        '200':
          description: Admission, replay, or semantic refusal
          headers:
            PAYMENT-RESPONSE:
              required: false
              description: Standard-base64 encoded external x402 v2 SettleResponse value on admission or replay
              schema:
                type: string
                minLength: 1
                maxLength: 65536
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvokeOfferResult'
        '402':
          description: External payment authority is required before invocation admission
          headers:
            PAYMENT-REQUIRED:
              required: true
              description: Standard-base64 encoded external x402 v2 PaymentRequired value
              schema:
                type: string
                minLength: 1
                maxLength: 65536
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/invocations/{invocation_id}:
    get:
      operationId: GetInvocation
      summary: Read authoritative invocation state
      description: Read the authoritative durable state, output commitment, and receipt reference for one invocation without creating a new purchase or retry identity.
      x-ausca-mcp:
        name: ausca_get_invocation
        inputSchema: '#/components/schemas/GetInvocationInput'
        resultSchema: '#/components/schemas/GetInvocationResult'
        readOnly: true
        destructive: false
        idempotent: true
        openWorld: false
        enabledByDefault: true
      parameters:
        - $ref: '#/components/parameters/InvocationID'
      responses:
        '200':
          description: Invocation state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvocationResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/invocations/{invocation_id}/cancel:
    post:
      operationId: CancelInvocation
      summary: Request bounded cancellation
      description: Request bounded cancellation of one invocation. Cancellation is idempotent, may be refused, and may lose a race with terminal completion.
      x-ausca-mcp:
        name: ausca_cancel_invocation
        inputSchema: '#/components/schemas/CancelInvocationInput'
        resultSchema: '#/components/schemas/CancelInvocationResult'
        readOnly: false
        destructive: true
        idempotent: true
        openWorld: true
        enabledByDefault: true
      parameters:
        - $ref: '#/components/parameters/InvocationID'
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelInvocationResult'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    OfferID:
      name: offer_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
    InvocationID:
      name: invocation_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
  responses:
    ErrorResponse:
      description: Transport or infrastructure failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
  schemas:
    Identifier:
      type: string
      minLength: 1
      maxLength: 128
      pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]*$'
    Digest:
      type: string
      pattern: '^sha256:[a-f0-9]{64}$'
    CatalogCursor:
      type: string
      minLength: 1
      maxLength: 512
      pattern: '^ausca:catalog-cursor:v1:[a-f0-9]{64}:[a-f0-9]{64}:[A-Za-z0-9_-]{2,171}$'
      description: Opaque, catalog-snapshot-bound continuation. Callers must not construct or modify it.
    SearchQuery:
      type: string
      minLength: 1
      maxLength: 256
      pattern: '^[^\s\x00-\x1F\x7F](?:[^\x00-\x1F\x7F]*[^\s\x00-\x1F\x7F])?$'
    SearchLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
    SearchOffersInput:
      type: object
      additionalProperties: false
      properties:
        q:
          $ref: '#/components/schemas/SearchQuery'
        limit:
          $ref: '#/components/schemas/SearchLimit'
        cursor:
          $ref: '#/components/schemas/CatalogCursor'
    GetOfferInput:
      type: object
      additionalProperties: false
      required: [offer_id]
      properties:
        offer_id:
          $ref: '#/components/schemas/Identifier'
        revision_digest:
          $ref: '#/components/schemas/Digest'
    GetInvocationInput:
      type: object
      additionalProperties: false
      required: [invocation_id]
      properties:
        invocation_id:
          $ref: '#/components/schemas/Identifier'
    CancelInvocationInput:
      $ref: '#/components/schemas/GetInvocationInput'
    OfferSummary:
      type: object
      additionalProperties: false
      required:
        - offer_id
        - offer_revision
        - offer_revision_digest
        - input_schema_digest
        - output_schema_digest
        - title
      properties:
        offer_id:
          $ref: '#/components/schemas/Identifier'
        offer_revision:
          $ref: '#/components/schemas/Identifier'
        offer_revision_digest:
          $ref: '#/components/schemas/Digest'
        input_schema_digest:
          $ref: '#/components/schemas/Digest'
        output_schema_digest:
          $ref: '#/components/schemas/Digest'
        title:
          type: string
          minLength: 1
          maxLength: 120
        description:
          type: string
          maxLength: 2000
    SearchOffersResult:
      type: object
      additionalProperties: false
      required: [status, offers]
      properties:
        status:
          const: ok
        offers:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/OfferSummary'
        next_cursor:
          $ref: '#/components/schemas/CatalogCursor'
    GetOfferResult:
      type: object
      additionalProperties: false
      required: [status, offer]
      properties:
        status:
          const: ok
        offer:
          $ref: '#/components/schemas/OfferSummary'
    ParentBinding:
      type: object
      additionalProperties: false
      required: [invocation_id, execution_digest]
      properties:
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        execution_digest:
          $ref: '#/components/schemas/Digest'
    InvocationEnvelope:
      type: object
      additionalProperties: false
      required:
        - offer_id
        - offer_revision
        - offer_revision_digest
        - input_schema_digest
        - output_schema_digest
        - canonicalizer_version
        - input
        - idempotency_key
      properties:
        offer_id:
          $ref: '#/components/schemas/Identifier'
        offer_revision:
          $ref: '#/components/schemas/Identifier'
        offer_revision_digest:
          $ref: '#/components/schemas/Digest'
        input_schema_digest:
          $ref: '#/components/schemas/Digest'
        output_schema_digest:
          $ref: '#/components/schemas/Digest'
        canonicalizer_version:
          const: runx.receipt.c14n.v1
        input: {}
        idempotency_key:
          type: string
          minLength: 16
          maxLength: 128
        parent_binding:
          $ref: '#/components/schemas/ParentBinding'
    PrepareInvocationRequest:
      $ref: '#/components/schemas/InvocationEnvelope'
    InvokeOfferRequest:
      $ref: '#/components/schemas/InvocationEnvelope'
    PaymentChallenge:
      type: object
      additionalProperties: false
      required:
        - settlement_family
        - protocol_version
        - media_type
        - payload
        - payload_digest
        - quote_ref
        - quote_expires_at
      properties:
        settlement_family:
          type: string
          minLength: 1
          maxLength: 64
        protocol_version:
          type: string
          minLength: 1
          maxLength: 32
        media_type:
          type: string
          minLength: 1
          maxLength: 128
        payload: {}
        payload_digest:
          $ref: '#/components/schemas/Digest'
        quote_ref:
          $ref: '#/components/schemas/Identifier'
        quote_expires_at:
          type: string
          format: date-time
    PreparedInvocation:
      type: object
      additionalProperties: false
      required: [status, invocation_id, challenge]
      properties:
        status:
          const: prepared
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        challenge:
          $ref: '#/components/schemas/PaymentChallenge'
    RefusedResult:
      type: object
      additionalProperties: false
      required: [status, code, reason]
      properties:
        status:
          const: refused
        code:
          type: string
          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
        reason:
          type: string
          minLength: 1
          maxLength: 512
    PrepareInvocationResult:
      oneOf:
        - $ref: '#/components/schemas/PreparedInvocation'
        - $ref: '#/components/schemas/RefusedResult'
    ReceiptReference:
      type: object
      additionalProperties: false
      required: [type, uri]
      properties:
        type:
          const: receipt
        uri:
          type: string
          minLength: 14
          maxLength: 512
          pattern: '^runx:receipt:.+$'
    InvocationState:
      type: object
      additionalProperties: false
      required:
        - invocation_id
        - offer_revision_digest
        - state
        - updated_at
      properties:
        invocation_id:
          $ref: '#/components/schemas/Identifier'
        offer_revision_digest:
          $ref: '#/components/schemas/Digest'
        state:
          type: string
          enum: [admitted, running, succeeded, failed, cancellation_requested, cancelled]
        updated_at:
          type: string
          format: date-time
        output: {}
        output_digest:
          $ref: '#/components/schemas/Digest'
        receipt_ref:
          $ref: '#/components/schemas/ReceiptReference'
    AcceptedInvocation:
      type: object
      additionalProperties: false
      required: [status, invocation]
      properties:
        status:
          const: accepted
        invocation:
          $ref: '#/components/schemas/InvocationState'
    ReplayedInvocation:
      type: object
      additionalProperties: false
      required: [status, invocation]
      properties:
        status:
          const: replayed
        invocation:
          $ref: '#/components/schemas/InvocationState'
    InvokeOfferResult:
      oneOf:
        - $ref: '#/components/schemas/AcceptedInvocation'
        - $ref: '#/components/schemas/ReplayedInvocation'
        - $ref: '#/components/schemas/RefusedResult'
    GetInvocationResult:
      oneOf:
        - type: object
          additionalProperties: false
          required: [status, invocation]
          properties:
            status:
              const: ok
            invocation:
              $ref: '#/components/schemas/InvocationState'
        - $ref: '#/components/schemas/RefusedResult'
    CancelInvocationResult:
      oneOf:
        - type: object
          additionalProperties: false
          required: [status, invocation]
          properties:
            status:
              type: string
              enum: [cancellation_requested, already_terminal]
            invocation:
              $ref: '#/components/schemas/InvocationState'
        - $ref: '#/components/schemas/RefusedResult'
    ErrorResult:
      type: object
      additionalProperties: false
      required: [status, code, message]
      properties:
        status:
          const: error
        code:
          type: string
          enum: [invalid_request, not_found, conflict, payment_required, unavailable]
        message:
          type: string
          minLength: 1
          maxLength: 512