{
  "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 \u00b7 MCP: npx -y milypay mcp \u00b7 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."
      }
    }
  }
}