{
  "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."
    },
    {
      "name": "Utilities",
      "description": "Live reference lookups proxied from public sources."
    }
  ],
  "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/icd10": {
      "get": {
        "tags": [
          "Utilities"
        ],
        "summary": "ICD-10-CM diagnosis-code autocomplete",
        "operationId": "searchIcd10",
        "description": "Live proxy of the NLM Clinical Table Search Service (U.S. National Library of Medicine, public domain), edge-cached. ICD-10-CM is the U.S. Clinical Modification — a reference lookup, not a diagnostic or coding authority.",
        "parameters": [
          {
            "name": "terms",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "description": "Search text — a diagnosis name or partial ICD-10 code (minimum 2 characters)."
          },
          {
            "name": "maxList",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 12
            },
            "description": "Maximum number of results (1–20)."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching ICD-10-CM codes (empty array when the query is under 2 characters or nothing matches).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Icd10Code"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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"
        ]
      },
      "Icd10Code": {
        "type": "object",
        "required": [
          "code",
          "name"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "E11.9",
            "description": "ICD-10-CM code."
          },
          "name": {
            "type": "string",
            "example": "Type 2 diabetes mellitus without complications",
            "description": "Code description."
          }
        }
      }
    }
  }
}