{
  "openapi": "3.1.0",
  "info": {
    "title": "PainMap public read-only data contract",
    "version": "2026-05-31.atlas.2",
    "description": "Static API contract for immutable PainMap releases, places, layers, sources, provenance, catalog, and geometry exports."
  },
  "servers": [
    {
      "url": "https://painmap.org"
    }
  ],
  "paths": {
    "/v1/releases.json": {
      "get": {
        "summary": "Get release index",
        "responses": {
          "200": {
            "description": "Release index JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/layers.json": {
      "get": {
        "summary": "Get layer definitions",
        "responses": {
          "200": {
            "description": "Layer definitions JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources.json": {
      "get": {
        "summary": "Get source registry",
        "responses": {
          "200": {
            "description": "Source registry JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/index.json": {
      "get": {
        "summary": "Get full release place index",
        "responses": {
          "200": {
            "description": "Place index JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceIndex"
                }
              }
            }
          }
        }
      }
    },
    "/v1/adm1/index.json": {
      "get": {
        "summary": "Get ADM1 poverty-context overlay index",
        "responses": {
          "200": {
            "description": "ADM1 context JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Adm1Context"
                }
              }
            }
          }
        }
      }
    },
    "/v1/coverage.json": {
      "get": {
        "summary": "Get release coverage status",
        "responses": {
          "200": {
            "description": "Coverage status JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoverageStatus"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/WLD.json": {
      "get": {
        "summary": "Get world place profile",
        "responses": {
          "200": {
            "description": "Place profile JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/{place_id}.json": {
      "get": {
        "summary": "Get release place profile when canonical measurements exist",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Place profile JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/{place_id}/measurements.json": {
      "get": {
        "summary": "Get release measurements for a place profile",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Place measurements for one place",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/{place_id}/neighbors.json": {
      "get": {
        "summary": "Get geographic neighbor and nearby-place metadata for a place",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Place neighbor payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/{place_id}/adm1.json": {
      "get": {
        "summary": "Get ADM1 poverty-context rows for a country",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country ADM1 context JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Adm1Context"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/BRA.json": {
      "get": {
        "summary": "Get Brazil place profile",
        "responses": {
          "200": {
            "description": "Place profile JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/BRA/neighbors.json": {
      "get": {
        "summary": "Get Brazil neighbor payload",
        "responses": {
          "200": {
            "description": "Place neighbor payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/IND.json": {
      "get": {
        "summary": "Get India place profile",
        "responses": {
          "200": {
            "description": "Place profile JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/places/IND/neighbors.json": {
      "get": {
        "summary": "Get India neighbor payload",
        "responses": {
          "200": {
            "description": "Place neighbor payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/releases/2026-05-31/manifest.json": {
      "get": {
        "summary": "Get immutable release manifest",
        "responses": {
          "200": {
            "description": "Release manifest JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/releases/2026-05-31/diff.json": {
      "get": {
        "summary": "Get release diff artifact",
        "responses": {
          "200": {
            "description": "Release diff JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/releases/2026-05-31/migration.json": {
      "get": {
        "summary": "Get release migration notes",
        "responses": {
          "200": {
            "description": "Release migration JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/latest/manifest.json": {
      "get": {
        "summary": "Get latest release alias manifest",
        "responses": {
          "200": {
            "description": "Latest alias JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/provenance-registry.json": {
      "get": {
        "summary": "Get dataset, source, license, evidence-kind, and uncertainty registry",
        "responses": {
          "200": {
            "description": "Provenance registry JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvenanceRegistry"
                }
              }
            }
          }
        }
      }
    },
    "/data/place-measurements.json": {
      "get": {
        "summary": "Get canonical place-level pain-source measurements",
        "responses": {
          "200": {
            "description": "Place measurements JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceMeasurements"
                }
              }
            }
          }
        }
      }
    },
    "/data/place-measurements.csv": {
      "get": {
        "summary": "Get canonical place-level measurements as CSV",
        "responses": {
          "200": {
            "description": "Place measurements CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/data/places.geojson": {
      "get": {
        "summary": "Get canonical place features for the atlas contract",
        "responses": {
          "200": {
            "description": "GeoJSON feature collection",
            "content": {
              "application/geo+json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureCollection"
                }
              }
            }
          }
        }
      }
    },
    "/data/dcat.json": {
      "get": {
        "summary": "Get DCAT-style dataset catalog",
        "responses": {
          "200": {
            "description": "Dataset catalog JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/release-modes.json": {
      "get": {
        "summary": "Get snapshot and live overlay release-mode contract",
        "responses": {
          "200": {
            "description": "Release-mode contract JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReleaseModes"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/index.json": {
      "get": {
        "summary": "Get OGC API - Features landing document",
        "responses": {
          "200": {
            "description": "OGC landing document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/conformance.json": {
      "get": {
        "summary": "Get OGC conformance classes",
        "responses": {
          "200": {
            "description": "OGC conformance document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/collections/index.json": {
      "get": {
        "summary": "Get OGC collection list",
        "responses": {
          "200": {
            "description": "OGC collections document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/collections/places/index.json": {
      "get": {
        "summary": "Get OGC places collection metadata",
        "responses": {
          "200": {
            "description": "OGC collection metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/collections/places/items.json": {
      "get": {
        "summary": "Get OGC-style GeoJSON country place features",
        "responses": {
          "200": {
            "description": "OGC-style GeoJSON feature collection",
            "content": {
              "application/geo+json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureCollection"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/collections/places/item-index.json": {
      "get": {
        "summary": "Get partitioned OGC country feature index",
        "responses": {
          "200": {
            "description": "Partitioned OGC country feature index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ogc/collections/places/items/{place_id}.json": {
      "get": {
        "summary": "Get one OGC-style GeoJSON country place feature",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OGC-style GeoJSON country feature",
            "content": {
              "application/geo+json": {
                "schema": {
                  "$ref": "#/components/schemas/Feature"
                }
              }
            }
          }
        }
      }
    },
    "/data/analytics-events.json": {
      "get": {
        "summary": "Get privacy-preserving telemetry event vocabulary",
        "responses": {
          "200": {
            "description": "Analytics event contract JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/performance-budgets.json": {
      "get": {
        "summary": "Get field performance budgets",
        "responses": {
          "200": {
            "description": "Performance budget JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/source-freshness.json": {
      "get": {
        "summary": "Get source freshness and scheduled refresh contract",
        "responses": {
          "200": {
            "description": "Source freshness contract JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/third-party-fetches.json": {
      "get": {
        "summary": "Get third-party fetch and release-materialization behavior matrix",
        "responses": {
          "200": {
            "description": "Third-party fetch behavior JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThirdPartyFetches"
                }
              }
            }
          }
        }
      }
    },
    "/data/accessibility-audit.json": {
      "get": {
        "summary": "Get WCAG 2.2 AA audit evidence matrix",
        "responses": {
          "200": {
            "description": "Accessibility audit JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessibilityAudit"
                }
              }
            }
          }
        }
      }
    },
    "/data/ui-smoke.json": {
      "get": {
        "summary": "Get accessibility and visual smoke-test manifest",
        "responses": {
          "200": {
            "description": "UI smoke manifest JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/endpoint-smoke.json": {
      "get": {
        "summary": "Get endpoint smoke-test manifest",
        "responses": {
          "200": {
            "description": "Endpoint smoke manifest JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/place-index.schema.json": {
      "get": {
        "summary": "Get JSON Schema for the place index",
        "responses": {
          "200": {
            "description": "Place index JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/place-measurements.schema.json": {
      "get": {
        "summary": "Get JSON Schema for place measurements",
        "responses": {
          "200": {
            "description": "Place measurements JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/adm1-context.schema.json": {
      "get": {
        "summary": "Get JSON Schema for ADM1 context",
        "responses": {
          "200": {
            "description": "ADM1 context JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/coverage.schema.json": {
      "get": {
        "summary": "Get JSON Schema for coverage status",
        "responses": {
          "200": {
            "description": "Coverage JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/release-modes.schema.json": {
      "get": {
        "summary": "Get JSON Schema for release modes",
        "responses": {
          "200": {
            "description": "Release modes JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/ogc-place-features.schema.json": {
      "get": {
        "summary": "Get JSON Schema for OGC-style place features",
        "responses": {
          "200": {
            "description": "OGC place features JSON Schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PlaceIndex": {
        "type": "object",
        "required": [
          "release_id",
          "count",
          "coverage_summary",
          "items"
        ]
      },
      "Adm1Context": {
        "type": "object",
        "required": [
          "release_id",
          "coverage_status",
          "count",
          "items"
        ]
      },
      "CoverageStatus": {
        "type": "object",
        "required": [
          "release_id",
          "coverage_status",
          "known_sparse_areas"
        ]
      },
      "ReleaseModes": {
        "type": "object",
        "required": [
          "release_id",
          "default_mode",
          "modes",
          "ui_contract"
        ]
      },
      "ThirdPartyFetches": {
        "type": "object",
        "required": [
          "release_id",
          "default_network_collection",
          "snapshot_mode_client_upstream_fetches",
          "modes",
          "domains"
        ]
      },
      "AccessibilityAudit": {
        "type": "object",
        "required": [
          "release_id",
          "standard",
          "target_conformance",
          "conformance_claim",
          "route_matrix",
          "open_items"
        ]
      },
      "ProvenanceRegistry": {
        "type": "object",
        "required": [
          "build",
          "methodClasses",
          "uncertaintyClasses",
          "licenses",
          "sources",
          "datasets"
        ]
      },
      "PlaceMeasurements": {
        "type": "object",
        "required": [
          "build",
          "measurements"
        ],
        "properties": {
          "build": {
            "type": "object"
          },
          "measurements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlaceMeasurement"
            }
          }
        }
      },
      "PlaceMeasurement": {
        "type": "object",
        "required": [
          "measurement_id",
          "release_id",
          "place_id",
          "place_name",
          "geometry_level",
          "layer_id",
          "layer_name",
          "evidence_kind",
          "value_type",
          "raw_value",
          "display_value",
          "unit_label",
          "ranking_mode",
          "source_ids",
          "confidence_low",
          "confidence_high",
          "provenance_id",
          "source_vintage",
          "extraction_timestamp",
          "transform_version",
          "reviewer_status",
          "source_file_checksum",
          "method_note",
          "uncertainty_class",
          "license_id"
        ],
        "properties": {
          "measurement_id": {
            "type": "string"
          },
          "release_id": {
            "type": "string"
          },
          "place_id": {
            "type": "string"
          },
          "place_name": {
            "type": "string"
          },
          "geometry_level": {
            "type": "string"
          },
          "layer_id": {
            "type": "string"
          },
          "layer_name": {
            "type": "string"
          },
          "evidence_kind": {
            "enum": [
              "direct",
              "modeled",
              "proxy",
              "priority-overlay",
              "boundary"
            ]
          },
          "value_type": {
            "type": "string"
          },
          "raw_value": {
            "type": "number"
          },
          "normalized_value": {
            "type": "number"
          },
          "display_value": {
            "type": "string"
          },
          "unit_label": {
            "type": "string"
          },
          "ranking_mode": {
            "type": "string"
          },
          "rank_value": {
            "type": "number"
          },
          "source_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "confidence_low": {
            "type": "number"
          },
          "confidence_high": {
            "type": "number"
          },
          "provenance_id": {
            "type": "string"
          },
          "source_vintage": {
            "type": "string"
          },
          "extraction_timestamp": {
            "type": "string"
          },
          "transform_version": {
            "type": "string"
          },
          "reviewer_status": {
            "enum": [
              "release-reviewed"
            ]
          },
          "source_file_checksum": {
            "type": "string"
          },
          "source_file_checksum_algorithm": {
            "const": "sha256"
          },
          "source_file_checksum_basis": {
            "type": "string"
          },
          "method_note": {
            "type": "string"
          },
          "uncertainty_class": {
            "enum": [
              "moderate",
              "low",
              "very-low"
            ]
          },
          "license_id": {
            "type": "string"
          }
        }
      },
      "FeatureCollection": {
        "type": "object",
        "required": [
          "type",
          "features"
        ],
        "properties": {
          "type": {
            "const": "FeatureCollection"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Feature": {
        "type": "object",
        "required": [
          "type",
          "id",
          "properties",
          "geometry"
        ],
        "properties": {
          "type": {
            "const": "Feature"
          },
          "id": {
            "type": "string"
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "properties": {
            "type": "object"
          },
          "geometry": {
            "type": "object"
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}