{
  "title": "Court records - choose dockets or opinions",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "searchType": {
      "title": "Record type to search",
      "type": "string",
      "description": "Dockets = RECAP federal court cases (parties, judges, firms, causes). Opinions = published case law / court opinions (citations, status).",
      "editor": "select",
      "default": "dockets",
      "enum": [
        "dockets",
        "opinions"
      ],
      "enumTitles": [
        "Court cases (RECAP dockets)",
        "Legal opinions (case law)"
      ],
      "sectionCaption": "1 · Court records",
      "sectionDescription": "Choose the record type and search scope first."
    },
    "keyword": {
      "title": "Keyword / query",
      "type": "string",
      "description": "Full-text search query, e.g. a company name, 'data breach', 'patent infringement'. Leave empty to browse the newest cases (with filters).",
      "editor": "textfield",
      "example": "\"data breach\""
    },
    "court": {
      "title": "Court ID",
      "type": "string",
      "description": "Restrict results to one CourtListener court ID, e.g. 'scotus' (Supreme Court), 'cand' (N.D. Cal.), 'nysd' (S.D.N.Y.), 'dcd' (D.D.C.). The ID must match exactly - an unknown ID returns zero results rather than an error, so leave this empty to search all courts.",
      "editor": "textfield",
      "example": "cand"
    },
    "filedSince": {
      "title": "Filed since",
      "type": "string",
      "description": "Only cases/opinions filed on or after this date (YYYY-MM-DD). Great for weekly litigation monitoring.",
      "editor": "textfield",
      "example": "2026-06-01",
      "sectionCaption": "2 · Dates and ordering",
      "sectionDescription": "Apply date boundaries and choose the source sort order."
    },
    "filedUntil": {
      "title": "Filed until",
      "type": "string",
      "description": "Only cases/opinions filed on or before this date (YYYY-MM-DD). Pair it with Filed since to pull one fixed window, e.g. a single quarter. When keyword, court, Filed since, and Filed until are all empty, the default search uses today's UTC date to exclude erroneous future-dated source records. Explicit queries and date filters are preserved.",
      "editor": "textfield",
      "example": "2026-06-30"
    },
    "orderBy": {
      "title": "Order by",
      "type": "string",
      "description": "Sort order. 'dateFiled desc' = newest first. 'score desc' = most relevant. 'citeCount desc' = most-cited (opinions).",
      "editor": "select",
      "default": "dateFiled desc",
      "enum": [
        "dateFiled desc",
        "dateFiled asc",
        "score desc",
        "citeCount desc"
      ],
      "enumTitles": [
        "Newest filed first",
        "Oldest filed first",
        "Most relevant",
        "Most cited (opinions)"
      ]
    },
    "maxResults": {
      "title": "Maximum case records",
      "type": "integer",
      "description": "Upper bound on records returned per run. CourtListener returns 20 records per request, so every 20 results costs one round-trip: 100 results takes roughly 15 seconds, 1000 takes roughly 4 minutes. Raise this freely on a filtered search; if you ask for a large number on a broad search, raise the run timeout in Run options too.",
      "editor": "number",
      "default": 100,
      "minimum": 1,
      "sectionCaption": "3 · Run limits",
      "sectionDescription": "Bound the collection before expanding your scope."
    },
    "maxRunSeconds": {
      "title": "Run time budget (seconds)",
      "type": "integer",
      "description": "Wall-clock budget for this run, in seconds. When it is reached the Actor stops cleanly and finishes successfully with the rows it already collected, instead of being killed mid-run. CourtListener returns 20 rows per request, so a run needs \"maxResults\" / 20 requests and single pages can stall for a minute. Raise it (and the run timeout in Run options) for a deliberately large job.",
      "editor": "number",
      "default": 240,
      "minimum": 30
    },
    "apiToken": {
      "title": "CourtListener API token (optional)",
      "type": "string",
      "description": "Optional free CourtListener API token for higher rate limits on large runs. Get one at courtlistener.com. Not required for normal use.",
      "editor": "textfield",
      "isSecret": true,
      "sectionCaption": "4 · Source access",
      "sectionDescription": "Follow the access requirements for your chosen record type."
    }
  },
  "description": "Choose the CourtListener record type and search scope, then set dates and a result cap. Check each source record and the run summary before interpreting an empty or partial result."
}