{
  "openapi": "3.1.0",
  "info": {
    "title": "Federal & State Law API",
    "version": "1.0",
    "description": "A free public API for U.S. legal data — federal and state statutes, court cases, legislative bills, and jurisdictions. No authentication required. Rate limit: 100 requests per minute. All content derives from public-domain U.S. legal materials and is released under CC0 1.0. This is a legal-information service, NOT a law firm or source of legal advice.",
    "contact": {
      "email": "contact@federalstatelaw.com"
    },
    "license": {
      "name": "CC0 1.0",
      "url": "https://creativecommons.org/publicdomain/zero/1.0/"
    },
    "termsOfService": "https://federalstatelaw.com/terms-of-service"
  },
  "servers": [
    {
      "url": "https://federalstatelaw.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API reference",
    "url": "https://federalstatelaw.com/developers/api-reference"
  },
  "paths": {
    "/api/v1/statutes": {
      "get": {
        "operationId": "listStatutes",
        "summary": "Search and filter U.S. federal and state statutes",
        "description": "Returns statute summaries with metadata. Supports filtering by jurisdiction and topic, with offset-based pagination.",
        "tags": [
          "Statutes"
        ],
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "Jurisdiction ID or abbreviation (e.g. \"federal\", \"california\", \"CA\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Topic keyword filter (e.g. \"civil-rights\", \"labor\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/LimitParam"
          },
          {
            "$ref": "#/components/parameters/OffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of statute summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatuteListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "fed-cra-1964",
                      "jurisdiction": "United States Federal",
                      "jurisdictionId": "federal",
                      "title": "Civil Rights Act of 1964 – Title VII",
                      "titleNumber": "42",
                      "sectionNumber": "§ 2000e",
                      "status": "active",
                      "effectiveDate": "1964-07-02",
                      "topics": [
                        "civil-rights",
                        "labor"
                      ],
                      "summary": "Employers cannot discriminate on the basis of race, color, religion, sex, or national origin.",
                      "meta": {
                        "source": "U.S. Code via Congress.gov",
                        "jurisdiction": "federal",
                        "last_updated": "2024-01-01",
                        "citation": "42 U.S.C. § 2000e",
                        "license": "CC0 1.0"
                      }
                    }
                  ],
                  "meta": {
                    "total": 12,
                    "limit": 5,
                    "offset": 0,
                    "hasMore": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/cases": {
      "get": {
        "operationId": "listCases",
        "summary": "Search and filter U.S. court cases",
        "description": "Returns court case summaries with citations and metadata. Supports filtering by jurisdiction, topic, and court level.",
        "tags": [
          "Cases"
        ],
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "Jurisdiction ID or name (e.g. \"federal\", \"new-york\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Topic keyword (e.g. \"civil-rights\", \"fourth-amendment\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "court",
            "in": "query",
            "required": false,
            "description": "Court name or level (e.g. \"supreme\", \"9th-circuit\", \"district\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/LimitParam"
          },
          {
            "$ref": "#/components/parameters/OffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of court case summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaseListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "brown-v-board-1954",
                      "caseName": "Brown v. Board of Education",
                      "citation": "347 U.S. 483 (1954)",
                      "court": "Supreme Court of the United States",
                      "jurisdiction": "United States Federal",
                      "jurisdictionId": "federal",
                      "decisionDate": "1954-05-17",
                      "topics": [
                        "civil-rights",
                        "education"
                      ],
                      "summary": "Racial segregation in public schools is unconstitutional.",
                      "meta": {
                        "source": "Supreme Court via CourtListener",
                        "jurisdiction": "federal",
                        "last_updated": "2024-01-01",
                        "citation": "347 U.S. 483",
                        "license": "CC0 1.0"
                      }
                    }
                  ],
                  "meta": {
                    "total": 8,
                    "limit": 5,
                    "offset": 0,
                    "hasMore": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/bills": {
      "get": {
        "operationId": "listBills",
        "summary": "Search and filter legislative bills",
        "description": "Returns legislative bill summaries. Supports filtering by status, chamber, jurisdiction, and topic.",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "Jurisdiction ID or name (e.g. \"federal\", \"texas\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Topic keyword (e.g. \"healthcare\", \"immigration\")",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Bill status filter",
            "schema": {
              "type": "string",
              "enum": [
                "in_committee",
                "passed_chamber",
                "signed"
              ]
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "description": "Legislative chamber",
            "schema": {
              "type": "string",
              "enum": [
                "senate",
                "house"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/LimitParam"
          },
          {
            "$ref": "#/components/parameters/OffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of legislative bill summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "hr-1-119",
                      "billNumber": "H.R. 1",
                      "title": "One Big Beautiful Bill Act",
                      "jurisdiction": "United States Federal",
                      "jurisdictionId": "federal",
                      "chamber": "house",
                      "status": "in_committee",
                      "introducedDate": "2025-01-09",
                      "topics": [
                        "budget",
                        "taxes"
                      ],
                      "summary": "Reconciliation bill addressing tax and spending provisions.",
                      "meta": {
                        "source": "Congress.gov",
                        "jurisdiction": "federal",
                        "last_updated": "2025-06-01",
                        "citation": "119th Cong., H.R. 1",
                        "license": "CC0 1.0"
                      }
                    }
                  ],
                  "meta": {
                    "total": 42,
                    "limit": 5,
                    "offset": 0,
                    "hasMore": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/jurisdictions": {
      "get": {
        "operationId": "listJurisdictions",
        "summary": "List all available jurisdictions",
        "description": "Returns all available jurisdictions including federal, all 50 states, DC, and U.S. territories. No parameters required.",
        "tags": [
          "Jurisdictions"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "The complete list of jurisdictions supported by the API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JurisdictionListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "federal",
                      "name": "United States Federal",
                      "abbreviation": "US",
                      "slug": "federal",
                      "level": "federal",
                      "capital": "Washington, D.C.",
                      "population": 331900000,
                      "meta": {
                        "source": "U.S. Census Bureau",
                        "jurisdiction": "federal",
                        "last_updated": "2024-01-01",
                        "citation": null,
                        "license": "CC0 1.0"
                      }
                    },
                    {
                      "id": "california",
                      "name": "California",
                      "abbreviation": "CA",
                      "slug": "california",
                      "level": "state",
                      "capital": "Sacramento",
                      "population": 39538223,
                      "meta": {
                        "source": "U.S. Census Bureau",
                        "jurisdiction": "california",
                        "last_updated": "2024-01-01",
                        "citation": null,
                        "license": "CC0 1.0"
                      }
                    }
                  ],
                  "meta": {
                    "total": 56
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Number of results per page. Default: 20. Maximum: 100.",
        "schema": {
          "type": "integer",
          "default": 20,
          "minimum": 1,
          "maximum": 100
        }
      },
      "OffsetParam": {
        "name": "offset",
        "in": "query",
        "required": false,
        "description": "Number of results to skip for pagination. Use with `limit` and `meta.hasMore`.",
        "schema": {
          "type": "integer",
          "default": 0,
          "minimum": 0
        }
      }
    },
    "schemas": {
      "ApiMeta": {
        "type": "object",
        "description": "Provenance and licensing metadata attached to every record.",
        "required": [
          "source",
          "jurisdiction",
          "last_updated",
          "license"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Originating data source (e.g. \"Congress.gov\", \"CourtListener\")."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Jurisdiction ID of the record."
          },
          "last_updated": {
            "type": "string",
            "format": "date",
            "description": "ISO 8601 date of last data refresh."
          },
          "citation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Formal legal citation string, if applicable."
          },
          "license": {
            "type": "string",
            "description": "Data license. Always \"CC0 1.0\" for this API.",
            "example": "CC0 1.0"
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "description": "Pagination envelope returned with every list response.",
        "required": [
          "total",
          "limit",
          "offset"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of results matching the query."
          },
          "limit": {
            "type": "integer",
            "description": "Page size used for this response."
          },
          "offset": {
            "type": "integer",
            "description": "Number of results skipped before this page."
          },
          "hasMore": {
            "type": "boolean",
            "description": "True if additional results are available beyond this page."
          }
        }
      },
      "JurisdictionOnlyMeta": {
        "type": "object",
        "description": "Abbreviated pagination meta for the jurisdictions endpoint (no hasMore).",
        "required": [
          "total"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of jurisdictions."
          }
        }
      },
      "Statute": {
        "type": "object",
        "description": "A U.S. federal or state statute with summary and provenance metadata.",
        "required": [
          "id",
          "jurisdiction",
          "jurisdictionId",
          "title",
          "status",
          "meta"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique statute identifier."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Human-readable jurisdiction name."
          },
          "jurisdictionId": {
            "type": "string",
            "description": "Machine-readable jurisdiction ID."
          },
          "title": {
            "type": "string",
            "description": "Statute title or popular name."
          },
          "titleNumber": {
            "type": "string",
            "description": "U.S.C. title number or state code equivalent."
          },
          "sectionNumber": {
            "type": "string",
            "description": "Section number (e.g. \"§ 2000e\")."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "repealed",
              "amended"
            ],
            "description": "Current legal status of the statute."
          },
          "effectiveDate": {
            "type": "string",
            "format": "date",
            "description": "Date the statute became effective."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Topic keyword tags."
          },
          "summary": {
            "type": "string",
            "description": "Plain-English summary of the statute."
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "Case": {
        "type": "object",
        "description": "A U.S. court case summary with citation and provenance metadata.",
        "required": [
          "id",
          "caseName",
          "citation",
          "court",
          "jurisdiction",
          "jurisdictionId",
          "meta"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique case identifier."
          },
          "caseName": {
            "type": "string",
            "description": "Case name (e.g. \"Brown v. Board of Education\")."
          },
          "citation": {
            "type": "string",
            "description": "Official reporter citation (e.g. \"347 U.S. 483 (1954)\")."
          },
          "court": {
            "type": "string",
            "description": "Full name of the deciding court."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Human-readable jurisdiction name."
          },
          "jurisdictionId": {
            "type": "string",
            "description": "Machine-readable jurisdiction ID."
          },
          "decisionDate": {
            "type": "string",
            "format": "date",
            "description": "Date the decision was issued."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Topic keyword tags."
          },
          "summary": {
            "type": "string",
            "description": "Plain-English summary of the holding."
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "Bill": {
        "type": "object",
        "description": "A U.S. federal or state legislative bill with summary and provenance metadata.",
        "required": [
          "id",
          "billNumber",
          "title",
          "jurisdiction",
          "jurisdictionId",
          "chamber",
          "status",
          "meta"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique bill identifier."
          },
          "billNumber": {
            "type": "string",
            "description": "Official bill number (e.g. \"H.R. 1\")."
          },
          "title": {
            "type": "string",
            "description": "Bill title."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Human-readable jurisdiction name."
          },
          "jurisdictionId": {
            "type": "string",
            "description": "Machine-readable jurisdiction ID."
          },
          "chamber": {
            "type": "string",
            "enum": [
              "senate",
              "house"
            ],
            "description": "Legislative chamber where the bill originated."
          },
          "status": {
            "type": "string",
            "enum": [
              "in_committee",
              "passed_chamber",
              "signed"
            ],
            "description": "Current legislative status."
          },
          "introducedDate": {
            "type": "string",
            "format": "date",
            "description": "Date the bill was introduced."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Topic keyword tags."
          },
          "summary": {
            "type": "string",
            "description": "Plain-English summary of the bill's purpose."
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "Jurisdiction": {
        "type": "object",
        "description": "A jurisdiction (federal, state, territory, or DC) with population and metadata.",
        "required": [
          "id",
          "name",
          "abbreviation",
          "slug",
          "level",
          "meta"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Machine-readable jurisdiction ID (e.g. \"federal\", \"california\")."
          },
          "name": {
            "type": "string",
            "description": "Full jurisdiction name (e.g. \"United States Federal\", \"California\")."
          },
          "abbreviation": {
            "type": "string",
            "description": "Standard postal or ISO abbreviation (e.g. \"US\", \"CA\")."
          },
          "slug": {
            "type": "string",
            "description": "URL slug used in site paths."
          },
          "level": {
            "type": "string",
            "enum": [
              "federal",
              "state",
              "territory",
              "district"
            ],
            "description": "Jurisdiction level."
          },
          "capital": {
            "type": "string",
            "description": "Capital city."
          },
          "population": {
            "type": "integer",
            "description": "Most recent Census population figure."
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "StatuteListResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Statute"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "CaseListResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Case"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "BillListResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Bill"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "JurisdictionListResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Jurisdiction"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/JurisdictionOnlyMeta"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          },
          "details": {
            "type": "object",
            "description": "Optional structured details about what went wrong.",
            "additionalProperties": true
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request contained invalid or missing parameters.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Invalid parameter: limit must be between 1 and 100."
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. The client has exceeded 100 requests per minute.",
        "headers": {
          "Retry-After": {
            "description": "Number of seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Rate limit exceeded. Retry after 60 seconds."
            }
          }
        }
      }
    }
  }
}