{
  "openapi": "3.1.0",
  "info": {
    "title": "The Treatment Registry API",
    "version": "1.0.0",
    "summary": "Open, read-only access to the registry's medical-tourism due-diligence data.",
    "description": "Public read API for The Treatment Registry. No authentication, no rate limits, CORS open to all origins (`Access-Control-Allow-Origin: *`); every endpoint also answers an `OPTIONS` preflight. Responses are edge-cached (`Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400`). For bulk access prefer the downloadable datasets under `/data` (see the Bulk data section) rather than paging these endpoints. Data is display/research use only — not medical or financial advice.\n\nWrite endpoints (`/api/submit-*`, `/api/newsletter`, token confirm/unsubscribe) are intentionally undocumented here — they are anti-spam-gated community plumbing, not part of the open data API.",
    "license": {
      "name": "CC BY-SA 4.0",
      "url": "https://creativecommons.org/licenses/by-sa/4.0/"
    },
    "contact": {
      "name": "The Treatment Registry",
      "url": "https://thetreatmentregistry.com/developers"
    }
  },
  "servers": [{ "url": "https://thetreatmentregistry.com" }],
  "externalDocs": {
    "description": "Developer guide + bulk-data catalogue",
    "url": "https://thetreatmentregistry.com/developers"
  },
  "tags": [
    { "name": "Entities", "description": "Collection projections (procedures, countries, clinics, …)." },
    { "name": "Citations", "description": "Per-entity machine-readable citation bundles (Markdown)." },
    { "name": "Bulk data", "description": "Whole-collection CSV / JSON downloads." }
  ],
  "paths": {
    "/api/procedures": {
      "get": {
        "tags": ["Entities"],
        "summary": "List published procedures",
        "operationId": "listProcedures",
        "responses": {
          "200": {
            "description": "All published procedures.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProcedureSummary" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/countries": {
      "get": {
        "tags": ["Entities"],
        "summary": "List published countries",
        "operationId": "listCountries",
        "responses": {
          "200": {
            "description": "All published destination countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountrySummary" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/clinics": {
      "get": {
        "tags": ["Entities"],
        "summary": "List or look up published clinics",
        "description": "Without parameters, returns all published clinics (full records). With `slug`, returns a single full clinic object or 404.",
        "operationId": "listClinics",
        "parameters": [
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by country slug." },
          { "name": "procedure", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to clinics offering this procedure slug." },
          { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return a single clinic by slug." }
        ],
        "responses": {
          "200": {
            "description": "Clinic list, or a single clinic when `slug` is given. Full clinic schema mirrors /data/clinics.json.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Array of clinic objects, or a single clinic object when queried by slug.",
                      "oneOf": [
                        { "type": "array", "items": { "$ref": "#/components/schemas/Clinic" } },
                        { "$ref": "#/components/schemas/Clinic" }
                      ]
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/accreditations": {
      "get": {
        "tags": ["Entities"],
        "summary": "List accreditations with clinic counts",
        "operationId": "listAccreditations",
        "parameters": [
          { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact accreditation name (case-insensitive)." },
          { "name": "expand", "in": "query", "required": false, "schema": { "type": "string", "enum": ["clinics"] }, "description": "Include the clinics holding each accreditation." }
        ],
        "responses": {
          "200": {
            "description": "Accreditations, optionally expanded with their clinics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Accreditation" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/glossary": {
      "get": {
        "tags": ["Entities"],
        "summary": "List glossary terms",
        "operationId": "listGlossary",
        "parameters": [
          { "name": "term", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a single term (case-insensitive)." },
          { "name": "procedure", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to terms related to a procedure slug." }
        ],
        "responses": {
          "200": {
            "description": "Glossary terms.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/GlossaryEntry" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/guides": {
      "get": {
        "tags": ["Entities"],
        "summary": "List published guides",
        "operationId": "listGuides",
        "parameters": [
          { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return a single guide by slug." }
        ],
        "responses": {
          "200": {
            "description": "Guide metadata (not the full body — fetch the page or /data/guides.json for content).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/GuideSummary" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/regulators": {
      "get": {
        "tags": ["Entities"],
        "summary": "List regulatory bodies",
        "operationId": "listRegulators",
        "parameters": [
          { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by country slug." },
          { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by regulator type." }
        ],
        "responses": {
          "200": {
            "description": "National medical/dental regulators.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Regulator" } },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/freshness": {
      "get": {
        "tags": ["Entities"],
        "summary": "Clinic verification freshness + review-cycle status",
        "operationId": "listFreshness",
        "responses": {
          "200": {
            "description": "Every published clinic with its lastVerified traffic-light bucket and nextReviewDue overdue status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/FreshnessEntry" } },
                    "meta": { "$ref": "#/components/schemas/FreshnessMeta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/citations/{type}/{slug}": {
      "get": {
        "tags": ["Citations"],
        "summary": "Per-entity Markdown citation bundle",
        "description": "One fetch returns an entity's full fields, resolved source URLs, and last-verified dates as `text/markdown` — built for LLM crawlers that want to cite one entity without parsing HTML.",
        "operationId": "getCitationBundle",
        "parameters": [
          { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["procedures", "clinics", "countries", "conditions"] } },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Markdown citation bundle.",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/data/index.json": {
      "get": {
        "tags": ["Bulk data"],
        "summary": "Open-data manifest",
        "description": "Machine-readable index of every bulk dataset: per-collection row counts and the CSV + JSON download URLs. Also available as a human catalogue at /data.",
        "operationId": "getDataManifest",
        "responses": {
          "200": {
            "description": "Dataset manifest.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataManifest" } } }
          }
        }
      }
    },
    "/data/registry.json": {
      "get": {
        "tags": ["Bulk data"],
        "summary": "Whole registry as one JSON document",
        "description": "Combined dump of all 12 published collections with a `_meta` block. Per-collection files are at `/data/{collection}.json` and `/data/{collection}.csv` (collections listed in /data/index.json).",
        "operationId": "getRegistryDump",
        "responses": {
          "200": {
            "description": "Combined registry export.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Entity not found.",
        "content": {
          "application/json": {
            "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] }
          }
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "description": "Standard response envelope metadata.",
        "properties": {
          "total": { "type": "integer", "description": "Number of items in `data` (list responses)." },
          "source": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "disclaimer": { "type": "string" }
        }
      },
      "FreshnessMeta": {
        "allOf": [
          { "$ref": "#/components/schemas/Meta" },
          {
            "type": "object",
            "properties": {
              "green": { "type": "integer", "description": "Verified within 6 months." },
              "amber": { "type": "integer", "description": "6–12 months old." },
              "red": { "type": "integer", "description": "Older than 12 months." },
              "overdue": { "type": "integer", "description": "Clinics past their nextReviewDue." },
              "rule": { "type": "string" }
            }
          }
        ]
      },
      "ProcedureSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "description": { "type": "string" },
          "priceRangeUSD": { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } } },
          "averageRecoveryDays": { "type": ["number", "null"] },
          "typicalSessions": { "type": ["number", "null"] }
        },
        "required": ["slug", "name"]
      },
      "CountrySummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "code": { "type": "string" },
          "regulatoryBody": { "type": "string" },
          "jciAccreditedCount": { "type": ["integer", "null"] },
          "commonProcedures": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["slug", "name"]
      },
      "Clinic": {
        "type": "object",
        "description": "Full clinic record. See /data/clinics.json for the complete field set.",
        "additionalProperties": true,
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "city": { "type": "string" },
          "verificationStatus": { "$ref": "#/components/schemas/VerificationStatus" },
          "lastVerified": { "type": "string", "format": "date" }
        },
        "required": ["slug", "name"]
      },
      "Accreditation": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "clinicCount": { "type": "integer" },
          "verifiedCount": { "type": "integer" },
          "clinics": {
            "type": "array",
            "description": "Present only with ?expand=clinics.",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "country": { "type": "string" },
                "verificationStatus": { "$ref": "#/components/schemas/VerificationStatus" },
                "verified": { "type": "boolean" }
              }
            }
          }
        },
        "required": ["name", "clinicCount", "verifiedCount"]
      },
      "GlossaryEntry": {
        "type": "object",
        "properties": {
          "term": { "type": "string" },
          "slug": { "type": "string" },
          "definition": { "type": "string" },
          "relatedProcedures": { "type": "array", "items": { "type": "string" } },
          "relatedCountries": { "type": "array", "items": { "type": "string" } },
          "relatedAccreditations": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["term", "slug", "definition"]
      },
      "GuideSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "status": { "type": "string" },
          "publishedAt": { "type": "string", "format": "date" },
          "updatedAt": { "type": "string", "format": "date" },
          "sources": { "type": "array", "items": { "type": "string" } },
          "relatedProcedures": { "type": "array", "items": { "type": "string" } },
          "relatedCountries": { "type": "array", "items": { "type": "string" } },
          "wordCount": { "type": "integer" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["slug", "title"]
      },
      "Regulator": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "type": { "type": "string" },
          "verificationUrl": { "type": "string", "format": "uri" },
          "description": { "type": "string" }
        },
        "required": ["slug", "name", "country"]
      },
      "FreshnessEntry": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "verificationStatus": { "$ref": "#/components/schemas/VerificationStatus" },
          "lastVerified": { "type": "string", "format": "date" },
          "bucket": { "type": "string", "enum": ["green", "amber", "red"] },
          "nextReviewDue": { "type": ["string", "null"], "format": "date" },
          "overdueDays": { "type": ["integer", "null"], "description": "Days past nextReviewDue; positive = overdue, negative = days remaining, null = no review date." }
        },
        "required": ["slug", "name", "bucket"]
      },
      "DataManifest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "attribution": { "type": "string" },
          "disclaimer": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date" },
          "combined": { "type": "object", "properties": { "json": { "type": "string" }, "csv": { "type": "string" } } },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "collection": { "type": "string" },
                "description": { "type": "string" },
                "rows": { "type": "integer" },
                "json": { "type": "string" },
                "csv": { "type": "string" }
              }
            }
          }
        }
      },
      "VerificationStatus": {
        "type": "string",
        "enum": ["verified", "partial", "unverified", "flagged"]
      }
    }
  }
}