Health Record Rights Cases API

openapi: 3.2.0
info:
  title: Health Record Rights Index Cases API
  version: '1'
  summary: Read-only JSON. Open, no sign-up, no key.
  description: Health record rights in countries and territories (scores out of 100, with sources), what each of the 50 states and DC adds to federal law (answers, no scores), and published real cases. Data version 1.0. Fields in v1 are never removed or renamed. Not legal advice.
  license:
    name: CC BY 4.0 (data and scores; quoted law, source titles and linked pages are not relicensed)
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    url: https://healthrecordrights.com/developers/
servers:
- url: https://healthrecordrights.com/api/v1
tags:
- name: Cases
paths:
  /cases:
    get:
      summary: Real cases
      description: Published accounts of real problems with health records, worldwide. They never change a score. With no parameter, every case. Parameters combine.
      parameters:
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-3 code, like GBR.
        schema:
          type: string
      - name: theme
        in: query
        required: false
        description: 'The kind of problem: access_refused, access_delay_or_cost, record_wrong, breach, sold_or_shared, lost_between_providers or other.'
        schema:
          type: string
      - name: since
        in: query
        required: false
        description: 'YYYY-MM-DD: only cases added to the index on or after this day (addedOn).'
        schema:
          type: string
      - name: lang
        in: query
        required: false
        description: Two-letter code of the source's language, like pt.
        schema:
          type: string
      - name: region
        in: query
        required: false
        description: Africa, Americas, Asia, Europe, Middle East or Oceania.
        schema:
          type: string
      responses:
        '200':
          description: The cases.
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        count:
                          type: integer
                        iso3:
                          type:
                          - string
                          - 'null'
                        filters:
                          type: object
                          properties:
                            theme:
                              type: string
                            since:
                              type: string
                            lang:
                              type: string
                            region:
                              type: string
                        howToCite:
                          type: string
                        cases:
                          type: array
                          items:
                            allOf:
                            - type: object
                              properties:
                                iso3:
                                  type: string
                                country:
                                  type: string
                            - $ref: '#/components/schemas/Case'
        '400':
          description: A query parameter could not be used. The body says why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found, with a plain message and, for a name or alias, the code to use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests. Wait the number of seconds in Retry-After.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: listCases
      tags:
      - Cases
  /cases/{caseId}:
    get:
      summary: One real case
      description: One case by its id. A removed case answers 410 Gone with its id, the day it was taken off and the class of removal, and nothing else.
      parameters:
      - name: caseId
        in: path
        required: true
        description: A case id, like FIN-S001.
        schema:
          type: string
        example: FIN-S001
      responses:
        '200':
          description: The case.
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        case:
                          allOf:
                          - type: object
                            properties:
                              iso3:
                                type: string
                              country:
                                type: string
                              citation:
                                type: string
                                description: The citation for this case, filled in.
                          - $ref: '#/components/schemas/Case'
        '400':
          description: A query parameter could not be used. The body says why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found, with a plain message and, for a name or alias, the code to use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: The case was taken off. The body says when and why, as a class; nothing else about it is kept.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests. Wait the number of seconds in Retry-After.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCase
      tags:
      - Cases
components:
  schemas:
    License:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        credit:
          type: string
        covers:
          type: string
        excludes:
          type: string
      required:
      - id
      - url
      - credit
    Case:
      type: object
      properties:
        date:
          type: string
        headline:
          type: string
        paraphrase:
          type: string
        source:
          type: string
        url:
          type: string
        archiveUrl:
          type: string
          description: 'Optional: a Wayback Machine copy of the source, saved when the case was published.'
        theme:
          type: string
        status:
          type: string
          enum:
          - finding
          - admitted
          - alleged
          - self_reported
        id:
          type: string
          description: 'The case id, like FIN-S001: it never changes and is never given to another case.'
        pageUrl:
          type: string
          description: The case on /real-cases/, the address to cite.
        countryUrl:
          type: string
          description: The country brief.
        why:
          type: string
          description: Why it matters to patients, in our words.
        sourceType:
          type: string
          enum:
          - regulator_decision
          - court_judgment
          - parliament_testimony
          - journalism
          - advocacy_case
          - own_blog
          description: The kind of source.
        lang:
          type: string
          description: Two-letter code of the source's language. Our summary is always English (inLanguage).
        providerName:
          type: string
          description: 'Optional: the hospital, company or other organization, named only when a regulator or court decided against it or it admitted the problem itself.'
        lastVerified:
          type: string
          format: date
          description: When the case was last checked against its source.
        addedOn:
          type: string
          format: date
          description: The day the case was added to the index; cases already in it when it was published carry October 2, 2026.
        archivedOn:
          type: string
          format: date
          description: 'Optional: the day the archived copy was made.'
        inLanguage:
          type: string
          description: 'The language of our headline and summary: en.'
    Error:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: 'null'
          error:
            type: object
            properties:
              status:
                type: integer
              code:
                type: string
                enum:
                - not_found
                - not_rated
                - use_code
                - not_covered
                - bad_request
                - method_not_allowed
                - rate_limited
                - server_error
                - gone
              message:
                type: string
              suggestions:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                    name:
                      type: string
                    url:
                      type: string
              removed:
                type: object
                properties:
                  id:
                    type: string
                  removedOn:
                    type: string
                  removalClass:
                    type: string
                    enum:
                    - window
                    - withdrawn
                description: 'A case taken down (410 only): its id, the day and why, as a class: past the two-year window (window) or withdrawn (withdrawn). Nothing else about the case is kept.'
            required:
            - status
            - code
            - message
    Envelope:
      type: object
      properties:
        api:
          const: v1
        version:
          type: string
          description: The index (data) version, like 1.0. Not the API version, which is api.
        asOf:
          type: string
          format: date
          description: The release date of the data, the same on every route. A country or state also carries its own date in data.
        dataSha256:
          type: string
          description: 'The release hash: SHA-256 of the country files behind the scores; the paper records the same hash. State answers are covered by statesSha256.'
        statesSha256:
          type: string
          description: 'State routes only: SHA-256 of the state files.'
        casesSha256:
          type: string
          description: 'Country and case routes: SHA-256 of the real cases, which the weekly refresh can change while dataSha256 stays the same.'
        casesAsOf:
          type: string
          format: date
          description: 'Country and case routes: the day the real cases last changed (a case added or taken off), from the changes journal. The index asOf is the data date and stays separate.'
        license:
          $ref: '#/components/schemas/License'
        citation:
          type: string
          description: How to cite the index.
        pageUrl:
          type: string
          description: The page on healthrecordrights.com that shows the same thing.
        data: {}
      required:
      - api
      - version
      - asOf
      - dataSha256
      - license
      - citation
      - pageUrl
      - data