Health Record Rights States API

openapi: 3.2.0
info:
  title: Health Record Rights Index States 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: States
paths:
  /states:
    get:
      summary: The 50 states and DC
      description: The list. No state score, total or rank.
      parameters: []
      responses:
        '200':
          description: The list.
          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:
                        stateCount:
                          type: integer
                          description: The 50 states. DC is listed too and is not counted here.
                        includesDC:
                          type: boolean
                        statesAsOf:
                          type: string
                        note:
                          type: string
                        states:
                          type: array
                          items:
                            $ref: '#/components/schemas/StateSummary'
        '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: listStates
      tags:
      - States
  /states/{usps}:
    get:
      summary: One state, or DC
      description: The answer to each question, with the laws quoted, dated and linked, and laws signed but not yet in force.
      parameters:
      - name: usps
        in: path
        required: true
        description: Two-letter code, like CA, or DC.
        schema:
          type: string
        example: CA
      responses:
        '200':
          description: The state.
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/State'
        '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: getState
      tags:
      - States
  /states/compare:
    get:
      summary: Compare two or three states
      description: Answers side by side, in the order given. Each row says differs, same or cannot_compare. No total, no rank and no winner.
      parameters:
      - name: s
        in: query
        required: true
        description: Two or three codes, comma separated, like CA,TX.
        schema:
          type: string
        example: CA,TX
      responses:
        '200':
          description: The comparison.
          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:
                        states:
                          type: array
                          items:
                            $ref: '#/components/schemas/StateSummary'
                        rule:
                          type: string
                        rows:
                          type: array
                          items:
                            $ref: '#/components/schemas/CompareRow'
        '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: compareStates
      tags:
      - States
components:
  schemas:
    Question:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        question:
          type: string
        status:
          type: string
          enum:
          - in_force
          - enacted_not_yet_effective
          - enjoined_or_stayed
          - repealed_or_superseded
          - no_law_found
          - not_checked
        statusText:
          type: string
        level:
          type:
          - integer
          - 'null'
        value:
          type:
          - string
          - 'null'
        answer:
          type: string
        short:
          type: string
        facts:
          type:
          - object
          - 'null'
          description: Recorded facts, as stored; fields vary by question and are not covered by the v1 promise. Where deadlineDays appears, deadlineScope (when present) says whom or what the deadline covers; give both together. Quotes inside feeRules are third-party text.
        provisions:
          type: array
          items:
            $ref: '#/components/schemas/Provision'
        pendingLaws:
          type: array
          items:
            type: object
            properties:
              title:
                type:
                - string
                - 'null'
              citation:
                type: string
              effectiveDate:
                type:
                - string
                - 'null'
        basis:
          type:
          - string
          - 'null'
          description: 'Exchange question only: what sets the rule (statute, regulation, executive_order or hie_policy).'
        designatedHie:
          type:
          - string
          - 'null'
          description: 'Exchange question only: the state-designated health information exchange, where recorded.'
        stricterForSensitive:
          type:
          - boolean
          - 'null'
          description: 'Exchange question only: some sensitive records need consent even where routine records do not.'
        legalNote:
          type: string
          description: 'Right-to-sue answers only: this records the law, not advice on whether to sue.'
        searchLog:
          type:
          - object
          - 'null'
          properties:
            searchedAt:
              type:
              - string
              - 'null'
            codeSearchUrl:
              type:
              - string
              - 'null'
            terms:
              type: array
              items:
                type: string
            agencyPagesChecked:
              type: array
              items:
                type: string
        pageUrl:
          type: string
    Provision:
      type: object
      properties:
        title:
          type:
          - string
          - 'null'
        citation:
          type: string
        officialUrl:
          type: string
        effectiveDate:
          type:
          - string
          - 'null'
        status:
          type: string
        statusText:
          type: string
        quote:
          type: string
          description: The words of the law, as quoted. Not relicensed.
        appliesTo:
          type:
          - string
          - 'null'
        checkedAt:
          type:
          - string
          - 'null'
        flags:
          type: array
          items:
            type: string
    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
    State:
      allOf:
      - $ref: '#/components/schemas/StateSummary'
      - type: object
        properties:
          fips:
            type: string
          note:
            type: string
          questions:
            type: array
            items:
              $ref: '#/components/schemas/Question'
    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
    StateSummary:
      type: object
      properties:
        usps:
          type: string
        name:
          type: string
        label:
          type: string
        isState:
          type: boolean
          description: False for Washington, DC, which is not a state.
        asOf:
          type: string
          description: When this state's laws were read.
        apiUrl:
          type: string
        pageUrl:
          type: string
    License:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        credit:
          type: string
        covers:
          type: string
        excludes:
          type: string
      required:
      - id
      - url
      - credit
    CompareRow:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        question:
          type: string
        comparison:
          type: string
          enum:
          - differs
          - same
          - cannot_compare
          description: 'cannot_compare: at least one answer was not checked.'
        answers:
          type: array
          items:
            type: object
            properties:
              usps:
                type: string
              checked:
                type: boolean
              status:
                type: string
              short:
                type: string
              answer:
                type:
                - string
                - 'null'
              pendingDates:
                type: array
                items:
                  type: string
              citations:
                type: array
                items:
                  type: string
              pageUrl:
                type: string