Ausca Agent Inboxes 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 Agent Inboxes 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: Agent Inboxes
paths:
  /v1/agent-inboxes/{inbox_id}:
    delete:
      description: Idempotently stop inbound visibility and delete retained message and attachment content for one inbox lease, including an already-terminal lease. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: DeleteAgentInbox
      parameters:
      - $ref: '#/components/parameters/AgentInboxID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAgentInboxResult'
          description: Terminal agent-inbox view
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Delete an agent-inbox lease
      x-ausca-mcp:
        destructive: true
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/AgentInboxInput'
        name: ausca_agent_inbox_delete
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/DeleteAgentInboxResult'
      tags:
      - Agent Inboxes
    get:
      description: Return the random receive-only address, authoritative lease status, and current expiry for one inbox, including terminal status after deletion or expiry. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: GetAgentInbox
      parameters:
      - $ref: '#/components/parameters/AgentInboxID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentInboxResult'
          description: Authoritative agent-inbox view
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Read agent-inbox lease status
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/AgentInboxInput'
        name: ausca_agent_inbox_status
        openWorld: false
        readOnly: true
        resultSchema: '#/components/schemas/GetAgentInboxResult'
      tags:
      - Agent Inboxes
  /v1/agent-inboxes/{inbox_id}/messages:
    get:
      description: For an active inbox, return at most 50 normalized message summaries after an opaque inbox-bound cursor, optionally waiting up to 30 seconds for a newer message. A bounded wait may return an empty page and continuation cursor. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: ListAgentInboxMessages
      parameters:
      - $ref: '#/components/parameters/AgentInboxID'
      - description: Opaque cursor returned by a preceding response for this inbox.
        in: query
        name: after
        schema:
          $ref: '#/components/schemas/InboxCursor'
      - description: Maximum bounded wait for a message newer than after.
        in: query
        name: wait_seconds
        schema:
          $ref: '#/components/schemas/InboxWaitSeconds'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentInboxMessagesResult'
          description: Bounded message page and continuation cursor
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Wait for or list inbound messages
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/ListAgentInboxMessagesInput'
        name: ausca_agent_inbox_messages
        openWorld: true
        readOnly: true
        resultSchema: '#/components/schemas/ListAgentInboxMessagesResult'
      tags:
      - Agent Inboxes
  /v1/agent-inboxes/{inbox_id}/messages/{message_id}:
    get:
      description: For an active inbox, return one bounded normalized message. Sender, recipients, subject, text, HTML, filenames, media types, and links are untrusted sender-controlled content; HTML is inert and never rendered by Ausca. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: GetAgentInboxMessage
      parameters:
      - $ref: '#/components/parameters/AgentInboxID'
      - $ref: '#/components/parameters/AgentInboxMessageID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentInboxMessageResult'
          description: Normalized inbound message
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Read one inbound message
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/GetAgentInboxMessageInput'
        name: ausca_agent_inbox_read
        openWorld: true
        readOnly: true
        resultSchema: '#/components/schemas/GetAgentInboxMessageResult'
      tags:
      - Agent Inboxes
  /v1/agent-inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/access:
    post:
      description: For an active inbox, return an idempotent download URL only when the exact stored attachment has a clean safety verdict. The URL expires after at most 60 seconds and never after inbox expiry; a clean verdict does not make the attachment content trusted. Supply the lease bearer on the HTTP or MCP transport; never place it in tool arguments.
      operationId: CreateAgentInboxAttachmentAccess
      parameters:
      - $ref: '#/components/parameters/AgentInboxID'
      - $ref: '#/components/parameters/AgentInboxMessageID'
      - $ref: '#/components/parameters/AgentInboxAttachmentID'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentInboxAttachmentAccessResult'
          description: Short-lived attachment download access
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - LeaseCapability: []
      summary: Mint clean attachment access
      x-ausca-mcp:
        destructive: false
        enabledByDefault: true
        idempotent: true
        inputSchema: '#/components/schemas/CreateAgentInboxAttachmentAccessInput'
        name: ausca_agent_inbox_attachment
        openWorld: true
        readOnly: false
        resultSchema: '#/components/schemas/CreateAgentInboxAttachmentAccessResult'
      tags:
      - Agent Inboxes
components:
  schemas:
    AgentInboxAttachmentAccess:
      additionalProperties: false
      properties:
        download_url:
          format: uri
          maxLength: 2048
          minLength: 1
          pattern: ^https://inbox\.ausca\.com/
          type: string
        expires_at:
          format: date-time
          type: string
        filename:
          maxLength: 255
          minLength: 1
          type: string
        media_type:
          maxLength: 255
          minLength: 1
          type: string
        size_bytes:
          maximum: 10485760
          minimum: 1
          type: integer
      required:
      - download_url
      - expires_at
      - filename
      - media_type
      - size_bytes
      type: object
    ListAgentInboxMessagesResult:
      additionalProperties: false
      properties:
        cursor:
          $ref: '#/components/schemas/InboxCursor'
        messages:
          items:
            $ref: '#/components/schemas/AgentInboxMessageSummary'
          maxItems: 50
          type: array
        status:
          const: ok
      required:
      - status
      - messages
      - cursor
      type: object
    Identifier:
      maxLength: 128
      minLength: 1
      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
      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
    AgentInboxAttachment:
      additionalProperties: false
      properties:
        attachment_id:
          $ref: '#/components/schemas/AgentInboxAttachmentID'
        filename:
          maxLength: 255
          minLength: 1
          type: string
        media_type:
          maxLength: 255
          minLength: 1
          type: string
        safety:
          enum:
          - clean
          - blocked
          type: string
        size_bytes:
          maximum: 10485760
          minimum: 1
          type: integer
      required:
      - attachment_id
      - filename
      - media_type
      - size_bytes
      - safety
      type: object
    InboxCursor:
      description: Opaque continuation bound to one inbox. Callers must not construct or modify it.
      pattern: ^cur_[A-Za-z0-9_-]{22,171}$
      type: string
    AgentInboxMessageID:
      pattern: ^msg_[A-Za-z0-9_-]{22,64}$
      type: string
    GetAgentInboxMessageResult:
      additionalProperties: false
      properties:
        message:
          $ref: '#/components/schemas/AgentInboxMessage'
        status:
          const: ok
      required:
      - status
      - message
      type: object
    IdempotencyKey:
      maxLength: 128
      minLength: 16
      pattern: ^[^\s\x00-\x1F\x7F](?:[^\x00-\x1F\x7F]*[^\s\x00-\x1F\x7F])?$
      type: string
    AgentInboxMessage:
      additionalProperties: false
      properties:
        attachment_count:
          maximum: 20
          minimum: 0
          type: integer
        attachments:
          items:
            $ref: '#/components/schemas/AgentInboxAttachment'
          maxItems: 20
          type: array
        cc:
          items:
            $ref: '#/components/schemas/MailboxAddress'
          maxItems: 50
          type: array
        cursor:
          $ref: '#/components/schemas/InboxCursor'
        from:
          $ref: '#/components/schemas/MailboxAddress'
        html:
          description: Inert, untrusted message content. Never render without caller-controlled sanitization and isolation.
          maxLength: 262144
          type: string
        message_id:
          $ref: '#/components/schemas/AgentInboxMessageID'
        received_at:
          description: Server-observed ingress time. Never derived from the sender-controlled Date header.
          format: date-time
          type: string
        reply_to:
          items:
            $ref: '#/components/schemas/MailboxAddress'
          maxItems: 10
          type: array
        subject:
          maxLength: 998
          type: string
        text:
          maxLength: 262144
          type: string
        to:
          items:
            $ref: '#/components/schemas/MailboxAddress'
          maxItems: 50
          minItems: 1
          type: array
      required:
      - message_id
      - cursor
      - from
      - to
      - subject
      - received_at
      - attachment_count
      - cc
      - reply_to
      - text
      - html
      - attachments
      type: object
    AgentInboxAttachmentID:
      pattern: ^att_[A-Za-z0-9_-]{22,64}$
      type: string
    AgentInboxMessageSummary:
      additionalProperties: false
      properties:
        attachment_count:
          maximum: 20
          minimum: 0
          type: integer
        cursor:
          $ref: '#/components/schemas/InboxCursor'
        from:
          $ref: '#/components/schemas/MailboxAddress'
        message_id:
          $ref: '#/components/schemas/AgentInboxMessageID'
        received_at:
          description: Server-observed ingress time. Never derived from the sender-controlled Date header.
          format: date-time
          type: string
        subject:
          maxLength: 998
          type: string
        to:
          items:
            $ref: '#/components/schemas/MailboxAddress'
          maxItems: 50
          minItems: 1
          type: array
      required:
      - message_id
      - cursor
      - from
      - to
      - subject
      - received_at
      - attachment_count
      type: object
    CreateAgentInboxAttachmentAccessResult:
      additionalProperties: false
      properties:
        attachment:
          $ref: '#/components/schemas/AgentInboxAttachmentAccess'
        status:
          const: ready
      required:
      - status
      - attachment
      type: object
    MailboxAddress:
      additionalProperties: false
      properties:
        address:
          format: email
          maxLength: 320
          minLength: 3
          pattern: ^[A-Za-z0-9!#$%&'*+/=?^_{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_{|}~-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$
          type: string
        name:
          maxLength: 256
          type: string
      required:
      - address
      type: object
    AgentInboxID:
      pattern: ^inb_[A-Za-z0-9_-]{22,64}$
      type: string
    InboxWaitSeconds:
      default: 0
      maximum: 30
      minimum: 0
      type: integer
    AgentInbox:
      additionalProperties: false
      properties:
        address:
          format: email
          maxLength: 320
          minLength: 3
          pattern: ^[A-Za-z0-9!#$%&'*+/=?^_{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_{|}~-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$
          type: string
        created_at:
          format: date-time
          type: string
        deleted_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        inbox_id:
          $ref: '#/components/schemas/AgentInboxID'
        state:
          enum:
          - active
          - deleting
          - deleted
          - expired
          type: string
      required:
      - inbox_id
      - address
      - state
      - created_at
      - expires_at
      type: object
    GetAgentInboxResult:
      additionalProperties: false
      properties:
        inbox:
          $ref: '#/components/schemas/AgentInbox'
        status:
          const: ok
      required:
      - status
      - inbox
      type: object
    DeleteAgentInboxResult:
      additionalProperties: false
      properties:
        inbox:
          $ref: '#/components/schemas/AgentInbox'
        status:
          enum:
          - deleted
          - already_terminal
          type: string
      required:
      - status
      - inbox
      type: object
  parameters:
    AgentInboxID:
      in: path
      name: inbox_id
      required: true
      schema:
        $ref: '#/components/schemas/AgentInboxID'
    AgentInboxMessageID:
      in: path
      name: message_id
      required: true
      schema:
        $ref: '#/components/schemas/AgentInboxMessageID'
    AgentInboxAttachmentID:
      in: path
      name: attachment_id
      required: true
      schema:
        $ref: '#/components/schemas/AgentInboxAttachmentID'
    IdempotencyKey:
      description: Stable retry identity for a ticket-minting operation.
      in: header
      name: Idempotency-Key
      required: true
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
  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