{
  "openapi": "3.1.0",
  "info": {
    "title": "Assay Systems register API",
    "version": "1.0.0",
    "description": "Public procurement register of 50+ countries as JSON: suppliers, buying offices, contracts, awards won without a rival. Summaries are free; the paid layer is pay-per-request over x402 (USDC on Base).",
    "x-guidance": "Free: GET /api/v1/search?q=<firm name>&country=<two-letter code> finds a supplier; GET /api/v1/supplier/{country}/{id} returns its record. Paid (x402, USD 0.01 a request, USDC on Base): GET /api/v1/solo lists countries with awards won without a rival; GET /api/v1/solo/{country}?kind=pairs|locks|buyers returns them; GET /api/v1/supplier/{country}/{id}/contracts and /api/v1/line/{country}/{id}/contracts return every contract as a row with the buying office's contact; GET /api/v1/ending?country=&line=&before=YYYY-MM-DD returns contracts ending soon. Call without payment to get the 402 challenge, then repeat with the PAYMENT-SIGNATURE header (x402 v2).",
    "contact": { "email": "contact@assay-systems.com", "url": "https://assay-systems.com/api-key/" }
  },
  "servers": [{ "url": "https://assay-systems.com" }],
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Search - find a supplier in the register (free)",
        "tags": ["Free"],
        "security": [],
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Firm name, two letters or more" },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "description": "Two-letter country code" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }
        ],
        "responses": { "200": { "description": "Matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "required": ["data"] } } } } }
      }
    },
    "/api/v1/supplier/{country}/{id}": {
      "get": {
        "operationId": "supplier",
        "summary": "Supplier - summary record of a firm (free)",
        "tags": ["Free"],
        "security": [],
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2}$" } },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Supplier id from /api/v1/search" }
        ],
        "responses": { "200": { "description": "Record", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "404": { "description": "No such record" } }
      }
    },
    "/api/v1/solo": {
      "get": {
        "operationId": "uncontestedIndex",
        "summary": "Uncontested - awards won without a rival (no competition or one bid): countries and counts, or one country's rows with ?country=",
        "tags": ["Paid"],
        "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] },
        "parameters": [
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "ca", "description": "Two-letter country code; without it the answer lists countries and counts" },
          { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pairs", "locks", "buyers"], "default": "pairs" }, "description": "With country: buyer-supplier pairs, locks or buyers' shares" },
          { "name": "buyer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With country: words of the buyer's name" },
          { "name": "supplier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With country: words of the supplier's name" },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "With country: page of rows" }
        ],
        "responses": {
          "200": { "description": "Countries and counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/api/v1/solo/{country}": {
      "get": {
        "operationId": "uncontested",
        "summary": "Uncontested - buyer and supplier pairs, locks and buyers' shares of awards won without a rival",
        "tags": ["Paid"],
        "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] },
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "ca" },
          { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pairs", "locks", "buyers"], "default": "pairs" } },
          { "name": "buyer", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "supplier", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/api/v1/supplier/{country}/{id}/contracts": {
      "get": {
        "operationId": "supplierContracts",
        "summary": "Contracts - every contract of a supplier as a row with the buying office's contact",
        "tags": ["Paid"],
        "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] },
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "ca" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Supplier id from /api/v1/search" },
          { "name": "ends_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "buyer", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Contract rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/api/v1/line/{country}/{id}/contracts": {
      "get": {
        "operationId": "lineContracts",
        "summary": "Contracts - every contract of a line of business as a row with the buying office's contact",
        "tags": ["Paid"],
        "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] },
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "ca" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Line id from /api/v1/line/{country}/{id}" },
          { "name": "ends_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "buyer", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Contract rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/api/v1/ending": {
      "get": {
        "operationId": "ending",
        "summary": "Ending - contracts of a line that end soon, with the buying office's contact",
        "tags": ["Paid"],
        "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] },
        "parameters": [
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "ca" },
          { "name": "line", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": { "description": "Contract rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } },
          "402": { "description": "Payment Required" }
        }
      }
    }
  }
}