{
  "openapi": "3.1.0",
  "info": {
    "title": "Lexedit public content API",
    "version": "1.0.0",
    "summary": "Read-only access to 1.4M Polish court rulings and 100K legal acts.",
    "description": "Public, unauthenticated JSON API over the Polish case-law and legislation corpus\nthat backs lexedit.ai. Use it to search rulings (Sąd Najwyższy, NSA, WSA, sądy\napelacyjne i powszechne, TSUE, KIO), read a ruling's full text, find rulings that\ncite a given provision, and read the text of a statute article as it stood on a\nspecific date.\n\nAuthentication: none. Fair use applies — this API serves the public website, so\nkeep to a few requests per second and cache what you fetch. There is no published\nquota; sustained or commercial use should be arranged via info@lexedit.ai.\n\nJurisdiction: Poland only. Content is predominantly Polish-language.\n\nNot covered here: the account-based research agent (app.lexedit.ai), the\ntranscription proxy, and internal revalidation hooks.",
    "contact": {
      "name": "Lexedit",
      "email": "info@lexedit.ai",
      "url": "https://lexedit.ai/developers"
    },
    "termsOfService": "https://lexedit.ai/pl/regulamin",
    "license": {
      "name": "Fair use — see terms of service",
      "url": "https://lexedit.ai/pl/regulamin"
    }
  },
  "servers": [
    {
      "url": "https://lexedit.ai",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer guide",
    "url": "https://lexedit.ai/developers"
  },
  "tags": [
    {
      "name": "case-law",
      "description": "Search and read Polish court rulings."
    },
    {
      "name": "legislation",
      "description": "Read Polish statutes, including historical versions."
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "search_rulings",
        "tags": [
          "case-law"
        ],
        "summary": "Search Polish court rulings",
        "description": "Full-text and case-number search across the ruling corpus, with faceted filters and paging. An exact sygnatura (case signature) match always ranks first. Set `smart=true` together with `q` for hybrid embedding search instead of keyword search.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search terms, matched against ruling summaries and case numbers. Supports AND (default), OR, \"phrase\" and -exclude.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "Restrict results to one corpus (e.g. 'saos', 'nsa'). Omit to search all.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "legal_area",
            "in": "query",
            "description": "Filter by top-level legal area, e.g. 'cywilne'. Values come from /api/search/filters.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "court_type",
            "in": "query",
            "description": "Filter by court tier, e.g. 'Sąd Najwyższy'. Values come from /api/search/filters.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "court_city",
            "in": "query",
            "description": "Filter by the city the court sits in.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Comma-separated topical tags; a ruling matches if it carries any of them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "description": "Only rulings issued on or after this date.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "description": "Only rulings issued on or before this date.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "precedential_strength",
            "in": "query",
            "description": "Filter by assessed precedential weight. Values come from /api/search/filters.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_final",
            "in": "query",
            "description": "Filter by finality (prawomocność).",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Result ordering. 'relevance' requires `q`.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "date_desc",
                "date_asc",
                "relevance"
              ],
              "default": "date_desc"
            }
          },
          {
            "name": "smart",
            "in": "query",
            "description": "Use hybrid embedding (semantic) search instead of keyword search. Requires `q`; falls back to keyword search if embedding fails.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip, for paging.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching rulings, newest first unless another sort was requested.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "Summary record of one court ruling, as returned by search endpoints.",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Lexedit extraction id; use it with /api/search/{id}."
                          },
                          "ruling_id": {
                            "type": "string",
                            "description": "Stable source-scoped ruling identifier."
                          },
                          "source": {
                            "type": "string",
                            "description": "Corpus the ruling came from.",
                            "examples": [
                              "saos",
                              "nsa",
                              "sn",
                              "tk",
                              "kio"
                            ]
                          },
                          "case_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Sygnatura akt (case signature), e.g. 'II CSK 123/19'. Null for rulings ingested without one."
                          },
                          "judgment_date": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date",
                            "description": "Date the judgment was issued."
                          },
                          "court_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Full name of the adjudicating court."
                          },
                          "court_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Court tier, e.g. 'Sąd Najwyższy', 'NSA', 'WSA', 'Sąd Apelacyjny'."
                          },
                          "court_city": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "City the court sits in."
                          },
                          "legal_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Top-level legal area, e.g. 'cywilne', 'karne', 'administracyjne'."
                          },
                          "legal_sub_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Narrower area within legal_area."
                          },
                          "tags": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "string"
                            },
                            "description": "Topical tags extracted from the ruling."
                          },
                          "summary_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "One-sentence summary of the holding."
                          },
                          "summary_synopsis": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Paragraph-length synopsis of the ruling."
                          },
                          "decision": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Disposition of the case."
                          },
                          "winner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Which side prevailed, when determinable."
                          },
                          "precedential_strength": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Assessed precedential weight of the ruling."
                          },
                          "judgment_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Wyrok, postanowienie, uchwała, etc."
                          },
                          "is_final": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "Whether the ruling is prawomocne (final)."
                          },
                          "costs_decision": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Ruling on the costs of proceedings."
                          },
                          "court_division_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Izba / wydział that decided the case."
                          },
                          "slug": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "SEO slug of the ruling page."
                          },
                          "url_path": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Canonical path segment for the ruling page under /orzeczenia."
                          },
                          "highlighted_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "summary_one_liner with <mark> tags around query matches. Present only when `q` was supplied."
                          },
                          "highlighted_synopsis": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "summary_synopsis with <mark> tags around query matches. Present only when `q` was supplied."
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Number of matching rulings. Approximate for unfiltered listings and capped at 10000 for text searches."
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Echo of the requested limit."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Echo of the requested offset."
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "Whether further pages exist."
                    }
                  },
                  "required": [
                    "results",
                    "total",
                    "limit",
                    "offset",
                    "has_more"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/{id}": {
      "get": {
        "operationId": "get_ruling_by_id",
        "tags": [
          "case-law"
        ],
        "summary": "Get one ruling by id",
        "description": "Full structured extraction of a single ruling: metadata, summaries, legal issues, cited provisions and quality signals. The `id` comes from the `id` field of a search result.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Lexedit extraction id, as returned in search results.",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ruling's full extraction record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Every field of rulingSummary plus the full extraction payload (legal issues, cited provisions, court answers) and provenance.",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Lexedit extraction id; use it with /api/search/{id}."
                    },
                    "ruling_id": {
                      "type": "string",
                      "description": "Stable source-scoped ruling identifier."
                    },
                    "source": {
                      "type": "string",
                      "description": "Corpus the ruling came from.",
                      "examples": [
                        "saos",
                        "nsa",
                        "sn",
                        "tk",
                        "kio"
                      ]
                    },
                    "case_number": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Sygnatura akt (case signature), e.g. 'II CSK 123/19'. Null for rulings ingested without one."
                    },
                    "judgment_date": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date",
                      "description": "Date the judgment was issued."
                    },
                    "court_name": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Full name of the adjudicating court."
                    },
                    "court_type": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Court tier, e.g. 'Sąd Najwyższy', 'NSA', 'WSA', 'Sąd Apelacyjny'."
                    },
                    "court_city": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "City the court sits in."
                    },
                    "legal_area": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Top-level legal area, e.g. 'cywilne', 'karne', 'administracyjne'."
                    },
                    "legal_sub_area": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Narrower area within legal_area."
                    },
                    "tags": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "string"
                      },
                      "description": "Topical tags extracted from the ruling."
                    },
                    "summary_one_liner": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "One-sentence summary of the holding."
                    },
                    "summary_synopsis": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Paragraph-length synopsis of the ruling."
                    },
                    "decision": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Disposition of the case."
                    },
                    "winner": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Which side prevailed, when determinable."
                    },
                    "precedential_strength": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Assessed precedential weight of the ruling."
                    },
                    "judgment_type": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Wyrok, postanowienie, uchwała, etc."
                    },
                    "is_final": {
                      "type": [
                        "boolean",
                        "null"
                      ],
                      "description": "Whether the ruling is prawomocne (final)."
                    },
                    "costs_decision": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Ruling on the costs of proceedings."
                    },
                    "court_division_name": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Izba / wydział that decided the case."
                    },
                    "slug": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "SEO slug of the ruling page."
                    },
                    "url_path": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Canonical path segment for the ruling page under /orzeczenia."
                    },
                    "highlighted_one_liner": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "summary_one_liner with <mark> tags around query matches. Present only when `q` was supplied."
                    },
                    "highlighted_synopsis": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "summary_synopsis with <mark> tags around query matches. Present only when `q` was supplied."
                    },
                    "summary_full": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Long-form summary of the ruling."
                    },
                    "citable_for": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "string"
                      },
                      "description": "Propositions the ruling can be cited for."
                    },
                    "limitations": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats limiting how far the ruling can be generalised."
                    },
                    "full_extraction": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Structured extraction payload, including `legal_issues` with court answers.",
                      "additionalProperties": true
                    },
                    "sygnatura": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Normalised case signature."
                    },
                    "quality_tier": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Internal quality tier of the extraction."
                    },
                    "extraction_confidence": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Model confidence in the extraction, 0-1."
                    },
                    "extracted_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "When the extraction ran."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No ruling with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/{id}/raw-text": {
      "get": {
        "operationId": "get_ruling_raw_text",
        "tags": [
          "case-law"
        ],
        "summary": "Get the original text of a ruling",
        "description": "The full original text of the ruling as published by the court, plus the source URL it was fetched from. Use this when you need to quote the judgment verbatim rather than rely on a summary.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Lexedit extraction id, as returned in search results.",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Original ruling text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "extraction_id": {
                      "type": "integer",
                      "description": "Echo of the requested id."
                    },
                    "ruling_id": {
                      "type": "string",
                      "description": "Stable source-scoped ruling identifier."
                    },
                    "case_number": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Sygnatura akt."
                    },
                    "raw_text": {
                      "type": "string",
                      "description": "Full text of the ruling as published."
                    },
                    "text_length": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Character length of raw_text."
                    },
                    "source_url": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri",
                      "description": "Public URL the text was fetched from."
                    },
                    "scraped_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "When the text was fetched."
                    }
                  },
                  "required": [
                    "extraction_id",
                    "ruling_id",
                    "raw_text"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No ruling with that id, or no text stored for it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/by-slug/{slug}": {
      "get": {
        "operationId": "get_ruling_by_slug",
        "tags": [
          "case-law"
        ],
        "summary": "Resolve a ruling page slug",
        "description": "Look up the ruling behind a public /orzeczenia URL slug. Slugs are not unique, so pass `ruling_id` when you have it — it takes priority and always resolves to exactly one ruling.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "SEO slug from the /orzeczenia URL.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ruling_id",
            "in": "query",
            "description": "Stable ruling identifier; disambiguates a shared slug.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ruling's full extraction record (same shape as get_ruling_by_id).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "Slug does not resolve to a ruling.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/provisions": {
      "get": {
        "operationId": "search_rulings_by_provision",
        "tags": [
          "case-law"
        ],
        "summary": "Find rulings citing a legal provision",
        "description": "Rulings that cite a given statutory provision, newest first. This is the fastest way to build a linia orzecznicza (line of case law) for an article.",
        "parameters": [
          {
            "name": "article",
            "in": "query",
            "description": "Provision to search for, as written in judgments, e.g. 'art. 118 k.c.' or 'art. 233 § 1 k.p.c.'.",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "Restrict results to one corpus (e.g. 'saos', 'nsa'). Omit to search all.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip, for paging.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rulings citing the provision.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "article": {
                      "type": "string",
                      "description": "Echo of the requested provision."
                    },
                    "source": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Echo of the source filter."
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "Summary record of one court ruling, as returned by search endpoints.",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Lexedit extraction id; use it with /api/search/{id}."
                          },
                          "ruling_id": {
                            "type": "string",
                            "description": "Stable source-scoped ruling identifier."
                          },
                          "source": {
                            "type": "string",
                            "description": "Corpus the ruling came from.",
                            "examples": [
                              "saos",
                              "nsa",
                              "sn",
                              "tk",
                              "kio"
                            ]
                          },
                          "case_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Sygnatura akt (case signature), e.g. 'II CSK 123/19'. Null for rulings ingested without one."
                          },
                          "judgment_date": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date",
                            "description": "Date the judgment was issued."
                          },
                          "court_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Full name of the adjudicating court."
                          },
                          "court_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Court tier, e.g. 'Sąd Najwyższy', 'NSA', 'WSA', 'Sąd Apelacyjny'."
                          },
                          "court_city": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "City the court sits in."
                          },
                          "legal_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Top-level legal area, e.g. 'cywilne', 'karne', 'administracyjne'."
                          },
                          "legal_sub_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Narrower area within legal_area."
                          },
                          "tags": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "string"
                            },
                            "description": "Topical tags extracted from the ruling."
                          },
                          "summary_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "One-sentence summary of the holding."
                          },
                          "summary_synopsis": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Paragraph-length synopsis of the ruling."
                          },
                          "decision": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Disposition of the case."
                          },
                          "winner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Which side prevailed, when determinable."
                          },
                          "precedential_strength": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Assessed precedential weight of the ruling."
                          },
                          "judgment_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Wyrok, postanowienie, uchwała, etc."
                          },
                          "is_final": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "Whether the ruling is prawomocne (final)."
                          },
                          "costs_decision": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Ruling on the costs of proceedings."
                          },
                          "court_division_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Izba / wydział that decided the case."
                          },
                          "slug": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "SEO slug of the ruling page."
                          },
                          "url_path": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Canonical path segment for the ruling page under /orzeczenia."
                          },
                          "highlighted_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "summary_one_liner with <mark> tags around query matches. Present only when `q` was supplied."
                          },
                          "highlighted_synopsis": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "summary_synopsis with <mark> tags around query matches. Present only when `q` was supplied."
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Number of rulings citing the provision."
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Echo of the requested limit."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Echo of the requested offset."
                    }
                  },
                  "required": [
                    "article",
                    "results",
                    "total",
                    "limit",
                    "offset"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/issues": {
      "get": {
        "operationId": "search_legal_issues",
        "tags": [
          "case-law"
        ],
        "summary": "Search the legal questions courts answered",
        "description": "Search across the legal issues extracted from rulings and return, for each hit, the matching issue and the court's answer. Use it when the question matters more than the case metadata.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "The legal question or phrase to search for.",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "Restrict results to one corpus (e.g. 'saos', 'nsa'). Omit to search all.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip, for paging.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rulings whose legal issues match the query.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string",
                      "description": "Echo of the query."
                    },
                    "source": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Echo of the source filter."
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Lexedit extraction id."
                          },
                          "ruling_id": {
                            "type": "string",
                            "description": "Stable ruling identifier."
                          },
                          "source": {
                            "type": "string",
                            "description": "Corpus the ruling came from."
                          },
                          "case_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Sygnatura akt."
                          },
                          "judgment_date": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date",
                            "description": "Date of judgment."
                          },
                          "court_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Adjudicating court."
                          },
                          "court_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Court tier."
                          },
                          "legal_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Legal area."
                          },
                          "summary_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "One-sentence summary."
                          },
                          "matching_issue": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The extracted legal issue that matched the query."
                          },
                          "court_answer": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "How the court answered that issue."
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Number of matching rulings."
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Echo of the requested limit."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Echo of the requested offset."
                    }
                  },
                  "required": [
                    "query",
                    "results",
                    "total",
                    "limit",
                    "offset"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/filters": {
      "get": {
        "operationId": "get_search_filters",
        "tags": [
          "case-law"
        ],
        "summary": "List available filter values with counts",
        "description": "Faceted filter options for the current filter set: each facet shows the values still available under the OTHER active filters. Call this before search_rulings to discover valid values for legal_area, court_type and friends.",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "description": "Restrict results to one corpus (e.g. 'saos', 'nsa'). Omit to search all.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Narrow facets to rulings matching this query.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "legal_area",
            "in": "query",
            "description": "Active legal-area filter.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "court_type",
            "in": "query",
            "description": "Active court-type filter.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "court_city",
            "in": "query",
            "description": "Active court-city filter.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "precedential_strength",
            "in": "query",
            "description": "Active precedential-strength filter.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_final",
            "in": "query",
            "description": "Active finality filter.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "description": "Active start-date filter.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "description": "Active end-date filter.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Active comma-separated tag filter.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available filter values with counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sources": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "legal_areas": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "court_types": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "court_cities": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "precedential_strengths": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "is_final_options": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "top_tags": {
                      "type": "array",
                      "description": "Facet values with the number of matching rulings under the other active filters.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "Facet value to pass back as a filter."
                          },
                          "count": {
                            "type": "integer",
                            "description": "Number of rulings with this value."
                          }
                        },
                        "required": [
                          "value",
                          "count"
                        ]
                      }
                    },
                    "total_count": {
                      "type": "integer",
                      "description": "Rulings matching all active filters."
                    }
                  },
                  "required": [
                    "sources",
                    "legal_areas",
                    "court_types",
                    "total_count"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search/stats": {
      "get": {
        "operationId": "get_corpus_stats",
        "tags": [
          "case-law"
        ],
        "summary": "Corpus size and composition",
        "description": "How many rulings the corpus holds and how they break down by source, legal area, court type and precedential strength, plus the ten most recently ingested rulings.",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "description": "Restrict results to one corpus (e.g. 'saos', 'nsa'). Omit to search all.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Corpus statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Total rulings in scope."
                    },
                    "by_source": {
                      "type": "object",
                      "description": "Ruling count per corpus.",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "by_legal_area": {
                      "type": "object",
                      "description": "Ruling count per legal area.",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "by_court_type": {
                      "type": "object",
                      "description": "Ruling count per court tier.",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "by_precedential_strength": {
                      "type": "object",
                      "description": "Ruling count per precedential-strength band.",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "recent": {
                      "type": "array",
                      "description": "Ten most recently ingested rulings.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ruling_id": {
                            "type": "string",
                            "description": "Stable ruling identifier."
                          },
                          "source": {
                            "type": "string",
                            "description": "Corpus the ruling came from."
                          },
                          "case_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Sygnatura akt."
                          },
                          "court_type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Court tier."
                          },
                          "legal_area": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Legal area."
                          },
                          "summary_one_liner": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "One-sentence summary."
                          },
                          "judgment_date": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date",
                            "description": "Date of judgment."
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "total"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Corpus backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/legislation/at-date": {
      "get": {
        "operationId": "get_statute_article_at_date",
        "tags": [
          "legislation"
        ],
        "summary": "Read a statute article as it stood on a date",
        "description": "The wording of a single article that was in force on the given date. Use this whenever the legal state at a past moment matters — the current text of a Polish statute is frequently not the text that governed the events in a case.",
        "parameters": [
          {
            "name": "eli",
            "in": "query",
            "description": "ELI identifier of the act, e.g. 'DU/1964/93' for the Kodeks cywilny.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "num",
            "in": "query",
            "description": "Article number as printed in the act, e.g. '118' or '305_1'.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date",
            "in": "query",
            "description": "Date the wording should be valid on, in YYYY-MM-DD form.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The article version in force on that date.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Internal version id."
                    },
                    "article_num": {
                      "type": "string",
                      "description": "Article number."
                    },
                    "version_date": {
                      "type": "string",
                      "format": "date",
                      "description": "Date this wording took effect."
                    },
                    "text": {
                      "type": "string",
                      "description": "Article text as in force on the requested date."
                    },
                    "act_title": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Title of the act."
                    }
                  },
                  "required": [
                    "id",
                    "article_num",
                    "version_date",
                    "text"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing eli, num or date.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No version of that article exists at that date.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Legislation backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/legislation/reader": {
      "get": {
        "operationId": "read_statute_window",
        "tags": [
          "legislation"
        ],
        "summary": "Read a window of an act's full text",
        "description": "A contiguous slice of an act's articles, in statutory order. Pass `around` to centre the window on one article (reading a cited provision in context), or `offset` with `limit` to page linearly through the act.",
        "parameters": [
          {
            "name": "eli",
            "in": "query",
            "description": "ELI identifier of the act, e.g. 'DU/1964/93'.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "around",
            "in": "query",
            "description": "Article number to centre the window on. Mutually exclusive with `offset`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Index of the first article to return, for linear paging. Defaults to 0 when `around` is absent.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "before",
            "in": "query",
            "description": "Articles to include before the `around` target.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100,
              "default": 15
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Articles to include after the `around` target.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100,
              "default": 30
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Articles to return when paging by `offset`.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 120,
              "default": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The requested slice of the act.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Total articles in the act."
                    },
                    "start_index": {
                      "type": "integer",
                      "description": "Index of the first returned article."
                    },
                    "target_index": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Index of the `around` article, when one was requested."
                    },
                    "articles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "article_num": {
                            "type": "string",
                            "description": "Article number."
                          },
                          "text": {
                            "type": "string",
                            "description": "Current text of the article."
                          },
                          "index": {
                            "type": "integer",
                            "description": "Position of the article within the act."
                          }
                        },
                        "required": [
                          "article_num",
                          "text",
                          "index"
                        ]
                      }
                    }
                  },
                  "required": [
                    "total",
                    "start_index",
                    "articles"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing eli.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Act or article not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Legislation backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error envelope returned for upstream or validation failures.",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Human-readable error message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}