openapi: 3.1.0
info:
  title: Milysec + Milypay Agent API Catalog
  version: 1.1.0
  summary: Discovery OpenAPI for Milysec studio and Milypay x402 data APIs
  description: "Milysec Pty Ltd studio site exposes discovery + contact. Executable pay-per-call Australian data APIs are on Milypay (x402). Auth on data plane: HTTP 402 payment proof (no long-lived API keys). CLI: npx -y milypay · MCP: npx -y milypay mcp · Docs: https://milysec.com/developers"
  contact:
    name: Milysec Developers
    url: "https://milysec.com/developers"
    email: "hello@milysec.com"
  license:
    name: Proprietary
    url: "https://milysec.com/privacy"
externalDocs:
  description: Milysec Developers portal
  url: "https://milysec.com/developers"
servers:
  -     url: "https://api.milypay.xyz"
    description: Milypay paid API (x402)
  -     url: "https://milypay.xyz/api"
    description: Milypay demo host (throttled)
  -     url: "https://milysec.com"
    description: Milysec studio + discovery
tags:
  -     name: discovery
    description: Studio machine-readable discovery
  -     name: studio-api
    description: Limited studio JSON endpoints (contact/newsletter)
  -     name: milypay-au-data
    description: Milypay Australian data over x402
paths:
  /llms.txt:
    get:
      tags:
        - discovery
      summary: Milysec llms.txt
      description: Short when-to-use brief for agents and crawlers.
      operationId: getMilysecLlms
      responses:
        200:
          description: text/plain brief
          content:
            text/plain:
              schema:
                type: string
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /llms-full.txt:
    get:
      tags:
        - discovery
      summary: Milysec llms-full.txt
      description: Long-form agent reference for the studio host.
      operationId: getMilysecLlmsFull
      responses:
        200:
          description: text/plain
          content:
            text/plain:
              schema:
                type: string
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /openapi.json:
    get:
      tags:
        - discovery
      summary: OpenAPI JSON
      description: This specification.
      operationId: getOpenApiJson
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /api/openapi.yaml:
    get:
      tags:
        - discovery
      summary: OpenAPI YAML
      description: YAML mirror of the OpenAPI catalog.
      operationId: getOpenApiYaml
      responses:
        200:
          description: YAML
          content:
            application/yaml:
              schema:
                type: string
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /.well-known/mcp.json:
    get:
      tags:
        - discovery
      summary: MCP discovery
      description: "Points agents at stdio MCP: npx -y milypay mcp"
      operationId: getMcpDiscovery
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /.well-known/api-catalog:
    get:
      tags:
        - discovery
      summary: API catalog linkset
      description: RFC 9727-style API catalog for Milysec and Milypay.
      operationId: getApiCatalog
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /developers:
    get:
      tags:
        - discovery
      summary: Developer portal (HTML)
      description: Human + agent developer portal with quickstart.
      operationId: getDevelopersPortal
      responses:
        200:
          description: HTML
          content:
            text/html:
              schema:
                type: string
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /api:
    get:
      tags:
        - studio-api
      summary: Studio API index
      description: JSON index of studio API routes and pointer to Milypay.
      operationId: getStudioApiIndex
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      servers:
        -           url: "https://milysec.com"
  /api/contact:
    post:
      tags:
        - studio-api
      summary: Contact form submit
      description: Human contact form. Returns JSON errors on failure.
      operationId: postContact
      servers:
        -           url: "https://milysec.com"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - message
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                message:
                  type: string
                company:
                  type: string
      responses:
        200:
          description: Accepted
          content:
            application/json:
              schema:
                type: object
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /au-business/abn/{abn}:
    get:
      tags:
        - milypay-au-data
      summary: ABN lookup
      description: Look up an Australian Business Number via Milypay x402. Function-calling friendly.
      operationId: getAbnLookup
      responses:
        200:
          description: ABN entity record
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbnRecord"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -           name: abn
          in: path
          required: true
          description: 11-digit ABN (spaces optional)
          schema:
          type: string
          pattern: "^[0-9 ]{11,14}$"
      servers:
        -           url: "https://api.milypay.xyz"
        -           url: "https://milypay.xyz/api"
  /au-company/acn/{acn}:
    get:
      tags:
        - milypay-au-data
      summary: ASIC company by ACN
      description: ASIC open-data company lookup by ACN via Milypay x402.
      operationId: getCompanyByAcn
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -           name: acn
          in: path
          required: true
          description: Australian Company Number
          schema:
          type: string
          minLength: 9
          maxLength: 11
      servers:
        -           url: "https://api.milypay.xyz"
        -           url: "https://milypay.xyz/api"
  /au-address/search:
    get:
      tags:
        - milypay-au-data
      summary: G-NAF address search
      description: Search and validate Australian addresses (G-NAF) via Milypay x402.
      operationId: searchAuAddress
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -           name: q
          in: query
          required: true
          description: Address query string
          schema:
          type: string
          minLength: 3
      servers:
        -           url: "https://api.milypay.xyz"
        -           url: "https://milypay.xyz/api"
  /au-bsb/{bsb}:
    get:
      tags:
        - milypay-au-data
      summary: BSB lookup
      description: Validate BSB and return bank/branch metadata via Milypay x402.
      operationId: getBsb
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Payment Required (x402). Pay quoted amount and retry with payment proof headers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -           name: bsb
          in: path
          required: true
          schema:
          type: string
          pattern: "^[0-9-]{6,7}$"
      servers:
        -           url: "https://api.milypay.xyz"
        -           url: "https://milypay.xyz/api"
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
              examples:
                - not_found
                - bad_request
            message:
              type: string
            status:
              type: integer
            resolution:
              type: string
            docs:
              type: string
              format: uri
    AbnRecord:
      type: object
      properties:
        abn:
          type: string
        entityName:
          type: string
        status:
          type: string
        entityType:
          type: string
      additionalProperties: true
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 payment proof after HTTP 402 challenge. No long-lived API keys.
