{
  "openapi": "3.1.0",
  "info": {
    "title": "Real Dental Costs Open Data API",
    "version": "1.0.0",
    "summary": "Free, open, no-key JSON API for U.S. dental cost data.",
    "description": "Static, versioned JSON endpoints generated at build time from the published Real Dental Costs datasets (51 U.S. state markets, 12 procedures, Medicaid acceptance, 2026 US Dental Cost Index). No authentication, CORS open. Attribution required (CC BY 4.0): link to https://realdentalcosts.com. The Restorative Cost Index is valid only for implant/crown/denture — it does not predict orthodontic or cosmetic prices.",
    "termsOfService": "https://realdentalcosts.com/en/terms-of-service/",
    "contact": {
      "name": "Real Dental Costs Data & Research Team",
      "email": "research@realdentalcosts.com",
      "url": "https://realdentalcosts.com/en/api/"
    },
    "license": {
      "name": "CC BY 4.0",
      "identifier": "CC-BY-4.0"
    }
  },
  "externalDocs": {
    "description": "Human documentation, methodology and citation formats",
    "url": "https://realdentalcosts.com/en/api/"
  },
  "servers": [
    {
      "url": "https://realdentalcosts.com/api/v1"
    }
  ],
  "paths": {
    "/index/meta.json": {
      "get": {
        "operationId": "getMeta",
        "summary": "Dataset metadata: edition, DOIs, license, versioning policy, endpoint index.",
        "responses": {
          "200": {
            "description": "Metadata document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meta"
                }
              }
            }
          }
        }
      }
    },
    "/states.json": {
      "get": {
        "operationId": "listStates",
        "summary": "Index of the 51 U.S. state markets (50 states + DC), cheapest to priciest on the Restorative Cost Index.",
        "responses": {
          "200": {
            "description": "State index.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateList"
                }
              }
            }
          }
        }
      }
    },
    "/state/{code}.json": {
      "get": {
        "operationId": "getState",
        "summary": "Full cost profile for one state: observed series, 12 procedure price bands, Medicaid acceptance, index and affordability.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "Two-letter state code, lowercase (e.g. ca, tx, ny, dc).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "State profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateProfile"
                }
              }
            }
          },
          "404": {
            "description": "Unknown state code."
          }
        }
      }
    },
    "/procedures.json": {
      "get": {
        "operationId": "listProcedures",
        "summary": "The 12 tracked procedures with national low/avg/high figures and their pricing basis.",
        "responses": {
          "200": {
            "description": "Procedure index.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcedureList"
                }
              }
            }
          }
        }
      }
    },
    "/procedure/{slug}.json": {
      "get": {
        "operationId": "getProcedure",
        "summary": "One procedure: national figures plus the [low, avg, high] band for each of the 51 state markets.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Stable procedure slug.",
            "schema": {
              "type": "string",
              "enum": [
                "all-on-4",
                "braces",
                "composite-filling",
                "deep-cleaning-srp",
                "dental-crown",
                "dental-implant",
                "dentures",
                "exam-cleaning-xrays",
                "porcelain-veneer",
                "root-canal",
                "teeth-whitening",
                "tooth-extraction"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Procedure detail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcedureDetail"
                }
              }
            }
          },
          "404": {
            "description": "Unknown procedure slug."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Meta": {
        "type": "object",
        "description": "Attribution and provenance block present on every payload.",
        "properties": {
          "api_version": {
            "type": "string",
            "const": "v1"
          },
          "edition": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "license": {
            "type": "string",
            "const": "CC-BY-4.0"
          },
          "license_url": {
            "type": "string",
            "format": "uri"
          },
          "attribution_required": {
            "type": "boolean"
          },
          "attribution": {
            "type": "string"
          },
          "doi": {
            "type": "string",
            "format": "uri"
          },
          "methodology": {
            "type": "string",
            "format": "uri"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "Basis": {
        "type": "string",
        "enum": [
          "observed",
          "estimated",
          "national"
        ],
        "description": "observed = the state average is a measured price (the low/high band around it is modelled); estimated = national figure scaled by the Restorative Cost Index (restorative regime only); national = no state variation is invented (cosmetic)."
      },
      "StateList": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "count": {
            "type": "integer",
            "const": 51
          },
          "note": {
            "type": "string"
          },
          "states": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "state": {
                  "type": "string"
                },
                "code": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "implant_avg_usd": {
                  "type": "number"
                },
                "restorative_cost_index": {
                  "type": "number",
                  "description": "100 = national observed implant average. Restorative regime only."
                },
                "affordability_score": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "StateProfile": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "state": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "restorative_cost_index": {
            "type": "object",
            "properties": {
              "value": {
                "type": "number"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "affordability_score": {
            "type": "number"
          },
          "medicaid": {
            "type": "object",
            "properties": {
              "pct_dentists_accepting": {
                "type": "number"
              },
              "adult_dental_coverage_level": {
                "type": "string",
                "enum": [
                  "extensive",
                  "limited",
                  "emergency_only",
                  "none"
                ]
              },
              "source": {
                "type": "string",
                "format": "uri"
              },
              "doi": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "observed_state_averages_usd": {
            "type": "object",
            "properties": {
              "note": {
                "type": "string"
              },
              "implant": {
                "type": "number"
              },
              "crown": {
                "type": "number"
              },
              "veneer": {
                "type": "number"
              },
              "braces": {
                "type": "number"
              },
              "denture_full_both_arches": {
                "type": "number"
              }
            }
          },
          "procedures": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "basis": {
                  "$ref": "#/components/schemas/Basis"
                },
                "basis_note": {
                  "type": "string"
                },
                "low_usd": {
                  "type": "number",
                  "description": "Low end of the price band, USD."
                },
                "avg_usd": {
                  "type": "number",
                  "description": "Average price, USD."
                },
                "high_usd": {
                  "type": "number",
                  "description": "High end of the price band, USD."
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "ProcedureList": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "count": {
            "type": "integer",
            "const": 12
          },
          "note": {
            "type": "string"
          },
          "procedures": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "basis": {
                  "$ref": "#/components/schemas/Basis"
                },
                "basis_note": {
                  "type": "string"
                },
                "national_low_usd": {
                  "type": "number"
                },
                "national_avg_usd": {
                  "type": "number"
                },
                "national_high_usd": {
                  "type": "number"
                },
                "cheapest_state": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "cheapest_state_avg_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "priciest_state": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "priciest_state_avg_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "ProcedureDetail": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "basis": {
            "$ref": "#/components/schemas/Basis"
          },
          "basis_note": {
            "type": "string"
          },
          "national": {
            "type": "object",
            "properties": {
              "low_usd": {
                "type": "number",
                "description": "Low end of the price band, USD."
              },
              "avg_usd": {
                "type": "number",
                "description": "Average price, USD."
              },
              "high_usd": {
                "type": "number",
                "description": "High end of the price band, USD."
              },
              "source": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "published_source_national": {
            "type": "object",
            "description": "Only present for observed series.",
            "properties": {
              "note": {
                "type": "string"
              },
              "avg_usd": {
                "type": "number"
              },
              "state_min_usd": {
                "type": "number"
              },
              "state_max_usd": {
                "type": "number"
              }
            }
          },
          "cheapest_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "cheapest_state_avg_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "priciest_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "priciest_state_avg_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "by_state": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "state": {
                  "type": "string"
                },
                "code": {
                  "type": "string"
                },
                "low_usd": {
                  "type": "number",
                  "description": "Low end of the price band, USD."
                },
                "avg_usd": {
                  "type": "number",
                  "description": "Average price, USD."
                },
                "high_usd": {
                  "type": "number",
                  "description": "High end of the price band, USD."
                }
              }
            }
          }
        }
      }
    }
  }
}