openapi: 3.1.0
info:
  title: OpenLaws API Documentation Courts Jurisdictions API
  version: 1.0.4
  description: OpenLaws Legal Data API
  contact:
    name: OpenLaws PBC
    url: https://openlaws.us/api
    email: team@openlaws.us
  license:
    name: Commercial
    url: https://openlaws.us/terms
servers:
- url: https://api.openlaws.us
security:
- bearerAuth: []
tags:
- name: Jurisdictions
  description: All data (statutes, regulations, caselaw opinions) in OpenLaws are organized into jurisdictions. This allows you to scope searches and lookups to a specific state or federal jurisdiction (or both).
paths:
  /api/v1/jurisdictions:
    get:
      summary: List all Jurisdictions
      description: Returns all valid jurisdictions, coverage data, and metadata for OpenLaws Jurisdictions
      tags:
      - Jurisdictions
      responses:
        '200':
          description: GET jurisdictions returns all jurisdictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jurisdiction'
        '401':
          $ref: '#/components/responses/unauthorized'
      operationId: listJurisdictions
components:
  schemas:
    Law:
      type: object
      description: Laws represent one type of codified or administrative law for a specific Jurisdiction. Laws contain Divisions. Please see the Court and Opinion schemas for case law.
      properties:
        key:
          type: string
          example: CA-RR
          description: OpenLaws identifier for the Law.
        jurisdiction_key:
          type: string
          example: CA
          description: State or province when applicable.
        state:
          type: string
          example: CA
          description: (Deprecated. Use `jurisdiction` instead.) State or province when applicable.
        law_type:
          type: string
          example: regulations
          description: Type of Law, including statutes, rules, regulations, court rules, constitution, case law
        name:
          type: string
          example: California Code of Regulations
          description: Jurisdiction's name for the Law
        aliases:
          type:
          - string
          - 'null'
          example: null
        features:
          type: array
          items:
            $ref: '#/components/schemas/LawFeature'
          description: For future use.
      required:
      - key
      - jurisdiction_key
      - law_type
    NullableDate:
      description: Nullable ISO 8601 Date
      type:
      - string
      - 'null'
      format: date
      example: '1776-04-01'
    Error:
      description: RFC9457 Problem Details
      type: object
      properties:
        status:
          type: integer
          example: 404
        title:
          type: string
        instance:
          type: string
        type:
          type: string
        details:
          type: string
        errors:
          type: array
          items:
            type: string
      required:
      - status
      - title
    LawFeature:
      description: Describes whether a Law has a type of data, e.g., rich text content, formatted tables.
      type: object
      properties:
        name:
          type: string
        available:
          type: boolean
    Jurisdiction:
      type: object
      description: Jurisdictions are the highest abstraction in OpenLaws. They contain codified Laws, Courts, Reporters. Federal is a special case and contains several "sub-Jurisdictions" due to the government's scale and complexity.
      properties:
        name:
          type: string
          example: California
        key:
          type: string
          description: Unique identifier for the jurisdiction. Often this is the same as postal_abbreviation (CA and TX) but not always (FED, FED-BANKR, MIL, and TRIBAL.)
          example: CA
        state:
          type: string
          description: '(DEPRECATION WARNING: Use ''key'' instead. Will be deprecated in 1.1.0) Unique identifier for the jurisdiction. Often this is the same as postal_abbreviation (CA and TX) but not always (FED)'
          example: CA
        abbreviation:
          type: string
          description: (FUTURE USE) Bluebook abbreviation for the Jurisdiction if applicable
          example: Cal.
        postal_abbreviation:
          description: (FUTURE USE)
          type: string
          example: CA
        laws:
          type: array
          items:
            $ref: '#/components/schemas/Law'
        courts:
          description: (FUTURE USE)
          type: array
          items:
            $ref: '#/components/schemas/Court'
            example: []
      required:
      - key
      - name
      - laws
    Court:
      description: Represents a single Court and closely aligns to CourtListener's data set. Courts contain Opinions.
      type: object
      properties:
        key:
          type: string
          example: scotus
          description: Unique identifier for the court
        jurisdiction_key:
          type: string
          example: FED
          description: Two to three letter Jurisdiction Key. `FED` for federal and generally, the postal abbreviation for most U.S. states and territories.
        parent_court_key:
          type:
          - string
          - 'null'
          example: null
          description: Parent court key if applicable
        name:
          type: string
          example: Supreme Court of the United States
        short_name:
          type: string
          example: Supreme Court
        abbreviation:
          type: string
          example: SCOTUS
        start_date:
          allOf:
          - $ref: '#/components/schemas/NullableDate'
          - example: '1789-09-24'
        end_date:
          allOf:
          - $ref: '#/components/schemas/NullableDate'
          - example: null
  responses:
    unauthorized:
      description: 401 Unauthorized. Please check your API Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      description: Authenticate API requests via a bearer token
      type: http
      scheme: bearer
      bearerFormat: JWT
x-ext-urls: {}