{
  "openapi": "3.1.0",
  "info": {
    "title": "AIready public scans and agent ordering API",
    "version": "1.0.0",
    "description": "Order AIready reports as an agent. Ordering returns HTTP 402 with Solana USDC payment instructions. Agentic Readiness Check payments are verified on-chain automatically via the confirm endpoint and the report is returned in seconds; Competitor Check and Deep Scan card payments (stripe_payment_url) are confirmed automatically by Stripe; their USDC payments are checked by the AIready team, usually within one business day. card_checkout_url is an alias of stripe_payment_url kept for compatibility.",
    "contact": {
      "name": "AIready",
      "email": "hello@aiready.nz",
      "url": "https://aiready.nz"
    }
  },
  "servers": [
    {
      "url": "https://aiready.nz"
    }
  ],
  "paths": {
    "/api/public/scan": {
      "get": {
        "operationId": "describePublicScan",
        "summary": "Describe free JSON scanning",
        "responses": {
          "200": {
            "description": "Scan usage"
          }
        }
      },
      "post": {
        "operationId": "createPublicScan",
        "summary": "Scan a public website; no account or order required",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "aiready.nz"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Public scan result, scan_id, warnings and result_url; no buyer or visitor identity"
          },
          "400": {
            "description": "Invalid domain"
          },
          "502": {
            "description": "Scan unavailable"
          }
        }
      }
    },
    "/api/public/scan/{scan_id}": {
      "get": {
        "operationId": "getPublicScan",
        "summary": "Read a saved public website scan",
        "parameters": [
          {
            "name": "scan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public website findings only"
          },
          "404": {
            "description": "Unknown scan"
          },
          "503": {
            "description": "Lookup unavailable"
          }
        }
      }
    },
    "/api/public/agent/order": {
      "get": {
        "operationId": "describeAgentOrder",
        "summary": "Describe the order request format",
        "responses": {
          "200": {
            "description": "Usage description",
            "content": {
              "application/json": {}
            }
          }
        }
      },
      "post": {
        "operationId": "createAgentOrder",
        "summary": "Create an order for an Agentic Readiness Check, Competitor Check or Deep Scan",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Stable 1–200 character retry key, scoped to the buyer email. Same input returns the same order; changed input returns 409.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product",
                  "domain",
                  "email"
                ],
                "properties": {
                  "product": {
                    "type": "string",
                    "enum": [
                      "agentic-readiness-check",
                      "agentic-readiness-check-test",
                      "competitor-check",
                      "deep-scan"
                    ]
                  },
                  "domain": {
                    "type": "string",
                    "example": "example.co.nz"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "competitors": {
                    "type": "array",
                    "maxItems": 5,
                    "items": {
                      "type": "string"
                    }
                  },
                  "dry_run": {
                    "type": "boolean",
                    "description": "Return prices and an intake link without creating an order or checkout session."
                  }
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocol": "solana-pay",
          "network": "solana",
          "currency": "USDC",
          "recipient": "39dAWDZZhR3ckKZ8tmf39MVzAtuWwTXU2WcY2DCN1WXy",
          "prices": {
            "agentic-readiness-check": 12,
            "agentic-readiness-check-test": 1,
            "competitor-check": 120,
            "deep-scan": 240
          },
          "confirmation": "automatic on-chain for agentic-readiness-check; manual for competitor-check and deep-scan"
        },
        "responses": {
          "200": {
            "description": "dry_run quote; order_created is false"
          },
          "400": {
            "description": "Invalid order"
          },
          "402": {
            "description": "Payment required. Body contains amount, recipient, token mint, memo and Solana Pay URL. Every order includes stripe_payment_url, a Stripe-hosted NZ$ card checkout bound to that order (null if card checkout is temporarily unavailable). Agentic Readiness Check orders also include card_checkout_url. Card payments are confirmed automatically by Stripe."
          },
          "409": {
            "description": "Retry key reused with different order details"
          },
          "429": {
            "description": "Too many open orders for this email"
          }
        }
      }
    },
    "/api/public/agent/order/{order_id}": {
      "get": {
        "operationId": "getAgentOrder",
        "summary": "Poll order status only; the report is never returned here and is emailed to the buyer as a private signed link",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order status: payment_required, confirming, in_progress, delivered, failed or rejected. The report field is always null; the report is emailed to the buyer as a private signed link."
          },
          "404": {
            "description": "Unknown order"
          }
        }
      }
    },
    "/api/public/agent/order/{order_id}/confirm": {
      "post": {
        "operationId": "confirmAgentOrder",
        "summary": "Submit the Solana transaction signature; payment is verified on-chain (mint, exact amount, recipient, memo, finalised, unused signature) and the Agentic Readiness Check report is generated immediately",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tx_signature"
                ],
                "properties": {
                  "tx_signature": {
                    "type": "string",
                    "description": "Base58 Solana transaction signature"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment verified; order status returned. The report is emailed to the buyer as a private signed link, not returned in this response."
          },
          "402": {
            "description": "Payment not verified on-chain; reason included"
          },
          "404": {
            "description": "Unknown order"
          },
          "409": {
            "description": "Order already confirmed, signature already used, or product confirmed manually"
          }
        }
      }
    }
  }
}