{
  "openapi": "3.1.0",
  "info": {
    "title": "PeptideClear Data API",
    "summary": "Read-only public data on UK peptide sellers and their Certificate-of-Analysis verification status.",
    "description": "Machine-readable access to PeptideClear's factual catalogue of UK peptide sellers: corporate identity, regulatory-status descriptors, and Certificate-of-Analysis (COA) verification signals (per-batch publishing, named third-party lab, QR-verifiable, CoA Trust Index tier), plus an aggregate COA snapshot. Source of truth is the on-site CoA Trust Index. This API contains factual catalogue and verification data only. It is NOT medical advice and nothing in it is a recommendation to use any substance. No prices, no efficacy claims, no dosing data. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-05-25",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "PeptideClear",
      "url": "https://peptideclear.co.uk/data/api/"
    }
  },
  "servers": [
    { "url": "https://peptideclear.co.uk", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://peptideclear.co.uk/data/api/"
  },
  "paths": {
    "/api/sellers": {
      "get": {
        "operationId": "listSellers",
        "summary": "List UK peptide sellers with COA verification data",
        "description": "Returns all tracked sellers, or a filtered subset when query params are supplied. Factual vendor / verification data only; no prices, no efficacy claims, no medical advice.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on seller name, summary, regulatory descriptor and lab partner.",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by seller category, e.g. research-peptide-retailer or high-touch-clinic.",
            "schema": { "type": "string" }
          },
          {
            "name": "coa_tier",
            "in": "query",
            "required": false,
            "description": "Filter research-peptide sellers by CoA Trust Index tier.",
            "schema": { "type": "string", "enum": ["green", "amber", "red"] }
          },
          {
            "name": "per_batch_coa",
            "in": "query",
            "required": false,
            "description": "Set to true to return only sellers that publish per-batch Certificates of Analysis.",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of sellers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "count": { "type": "integer" },
                    "sellers": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Seller" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sellers/{slug}": {
      "get": {
        "operationId": "getSeller",
        "summary": "Get a single seller by slug",
        "description": "Returns the verification record for one seller.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "pure-peptides-uk"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching seller.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "seller": { "$ref": "#/components/schemas/Seller" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No seller matches the slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/coa-snapshot": {
      "get": {
        "operationId": "getCoaSnapshot",
        "summary": "Aggregate UK research-peptide COA verification snapshot",
        "description": "Counts of UK research-peptide sellers by CoA Trust Index tier, per-batch publishing, named third-party lab and QR-verifiable COAs. Non-medical aggregate verification data; not a safety or efficacy judgement.",
        "responses": {
          "200": {
            "description": "COA verification snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CoaSnapshot" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Seller": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "category_label": { "type": "string" },
          "homepage": { "type": "string", "format": "uri" },
          "profile_url": { "type": "string", "format": "uri" },
          "summary": { "type": "string", "description": "Neutral catalogue descriptor as published on-site. Not a health claim." },
          "founded_year": { "type": ["integer", "null"] },
          "regulated": { "type": ["string", "null"], "description": "Regulatory or registration descriptor as published, e.g. GPhC pharmacy." },
          "companies_house": { "type": ["string", "null"] },
          "coa": {
            "type": "object",
            "description": "Certificate-of-Analysis verification signals.",
            "properties": {
              "per_batch": { "type": ["boolean", "null"] },
              "gating": { "type": ["string", "null"] },
              "qr_verifiable": { "type": ["boolean", "null"] },
              "lab_partner": { "type": ["string", "null"] },
              "url": { "type": ["string", "null"] },
              "trust_index": {
                "type": ["object", "null"],
                "properties": {
                  "tier": { "type": "string", "enum": ["green", "amber", "red", "n/a"] },
                  "score": { "type": ["number", "null"] },
                  "label": { "type": "string" },
                  "reasons": { "type": "array", "items": { "type": "string" } },
                  "flags": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          },
          "last_reviewed": { "type": "string", "format": "date" }
        },
        "required": ["slug", "name", "category", "profile_url", "coa"]
      },
      "CoaSnapshot": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "as_of": { "type": "string", "format": "date" },
          "region": { "type": "string" },
          "scope": { "type": "string" },
          "sellers_tracked": { "type": "integer" },
          "coa_trust_tiers": {
            "type": "object",
            "properties": {
              "green": { "type": "integer" },
              "amber": { "type": "integer" },
              "red": { "type": "integer" },
              "note": { "type": "string" }
            }
          },
          "per_batch_coa_published": { "type": "integer" },
          "named_third_party_lab": { "type": "integer" },
          "qr_verifiable_coa": { "type": "integer" },
          "methodology": { "type": "string", "format": "uri" },
          "source": { "type": "string", "format": "uri" },
          "disclaimer": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}