openapi: 3.1.0
info:
  title: SendaFax.ai — send a fax in Australia (+61)
  version: "1.0.0"
  summary: Send a fax to a +61 number; pay only if it delivers.
  description: |
    Identity is Google or Microsoft OAuth email. No card is taken at send time.
    The next fax is locked until the last invoice is paid.
    Last-mile delivery is Notifyre Australia (+61) only.
    Not HIPAA-certified. Not inbound fax. Not a blast tool.
  contact:
    name: SendaFax.ai
    url: https://sendafax.ai
servers:
  - url: https://sendafax.ai
    description: Production
paths:
  /api/faxes:
    post:
      operationId: sendFax
      summary: Send a fax to a +61 number; pay only if it delivers
      security:
        - SessionCookie: []
        - BearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendFaxRequest"
      responses:
        "200":
          description: Fax accepted by SendaFax
        "409":
          description: Account locked or another fax is in flight
        "422":
          description: Invalid destination, pages, or document
  /api/faxes/{id}:
    get:
      operationId: getFax
      summary: Get fax status without refreshing the carrier
      parameters:
        - $ref: "#/components/parameters/FaxId"
      security:
        - SessionCookie: []
        - BearerToken: []
      responses:
        "200":
          description: Fax job
  /api/faxes/{id}/refresh:
    post:
      operationId: refreshFax
      summary: Refresh delivery status from the last-mile carrier
      parameters:
        - $ref: "#/components/parameters/FaxId"
      security:
        - SessionCookie: []
        - BearerToken: []
      responses:
        "200":
          description: Updated fax job. An invoice is created only if the fax delivered.
  /api/invoices:
    get:
      operationId: listInvoices
      summary: List invoices for the signed-in account
      security:
        - SessionCookie: []
        - BearerToken: []
      responses:
        "200":
          description: Invoices
  /api/invoices/{id}/pay:
    post:
      operationId: payInvoice
      summary: Mark an invoice paid and unlock the next fax
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      security:
        - SessionCookie: []
        - BearerToken: []
      responses:
        "200":
          description: Invoice paid
  /api/mcp:
    post:
      operationId: mcp
      summary: Hosted MCP JSON-RPC endpoint
      description: Tools are send_fax (destructive, no default destination) and get_fax_status.
      security:
        - SessionCookie: []
        - BearerToken: []
      responses:
        "200":
          description: JSON-RPC response
components:
  parameters:
    FaxId:
      name: id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: authjs.session-token
    BearerToken:
      type: http
      scheme: bearer
  schemas:
    SendFaxRequest:
      type: object
      required: [destination, pages]
      additionalProperties: false
      properties:
        destination:
          type: string
          description: Australian fax number. Must be +61. No default.
          examples: ["+61299990000"]
        pages:
          type: integer
          minimum: 1
          maximum: 200
        pricingPlan:
          type: string
          enum: [per_page, pack_50]
          default: per_page
        text:
          type: string
          description: Plain-text body. Required unless base64 is sent.
        filename:
          type: string
        contentType:
          type: string
        base64:
          type: string
