Clarification on new invalid-GET-params warnings, canonical court slugs, and v4 behavior (observed in our integration)

[FoundaryCore]

Hi CourtListener team, We’ve started updating our integration and have a few specific questions to make sure we adapt correctly.

What we observed

• We saw the warning about invalid GET params (examples below). We updated our client to stop sending q to /courts/ and /opinions/, and to prefer the v4 endpoints when our token is present.
• In practice, some full_name__icontains queries returned 0 results (e.g., "Supreme Court of Texas"), while slug__icontains or /search/?q=court:"..." succeeds.
• We used cluster__docket__court=<slug> to filter opinions and that works on v4 when we use a slug (e.g., ca3 returned 20+ opinions).
• We observed occasional 403s on v4 in some runs and fell back to v3 for the same request.

Sanitized examples (no tokens included)

• GET /api/rest/v4/courts/?full_name__icontains=Supreme%20Court%20of%20Texas → 200 but results: 0
• GET /api/rest/v4/opinions/?cluster__docket__court=ca3 → 200, returns opinions (IDs shown)
• GET /api/rest/v4/search/?q=court:"Texas Supreme Court"&type=o → 200, returns clusters with opinions
• In some calls we saw warnings about invalid parameters; you mentioned those will be blocked starting Feb 10.

Questions

1. Canonical slugs: For state-level and district-group collections (e.g., TX Supreme, PA district groups, 3rd & 5th Circuits), is there an authoritative source or recommended search pattern to reliably discover the canonical slug? (We found ca3 for Third Circuit, texcrimapp for Texas CCA, but not a stable slug for all district groups.)
2. Preferred discovery flow: do you recommend (in order) — (A) courts/?slug__icontains=... → (B) /opinions/?cluster__docket__court=<slug> → (C) fallback to /search/?q=court:"..."&type=o ? Any other recommended parameters?
3. v4 access / 403s: when an authenticated token returns 403 for v4 on some endpoints, is that expected (token scope issue) or should v4 work consistently for all authenticated tokens? If scope-based, can you point to the exact authorization differences?
4. Invalid-param errors: you said the upcoming enforcement only disallows incorrect usage — any recommended canonical examples we can use in our test suite to pre-validate requests?
5. Debugging help: if helpful, we can share sanitized request/response pairs and a short log excerpt (no token) or a minimal repro using public endpoints — what’s the best place or format to attach them?

Attachments included:

• validation_report.json (summary of per-court validation samples)
• incremental_summary.json (current ok/partial/failed statuses)
• found_summary.json (terms that produced results via free-text search)
• districts_summary.json (district group query summary)
• sanitized_logs.txt (small log excerpt with tokens redacted)

Offer to help

• We have short logs, sample opinion IDs, and a small test script we can share. If there’s a preferred code snippet (curl/axios) or test case you’d like us to run and post, we can do that and report back.
  districts_summary.json
  found_summary.json
  incremental_summary.json
  sanitized_logs.txt
  validation_report.json

[mlissner]

We observed occasional 403s on v4 in some runs and fell back to v3 for the same request.

That's weird. Don't use the v3 because it will cut you off fairly soon. It only checks 1/1000 requests for performance, but once you're blocked, you're blocked.

For v4 and 403's, it's helpful to have some queries to debug.

In practice, some full_name__icontains queries returned 0 results (e.g., "Supreme Court of Texas"), while slug__icontains or /search/?q=court:"..." succeeds.

If you have URLs, we can sort out what's up.

GET /api/rest/v4/opinions/?cluster__docket__court=ca3 → 200, returns opinions (IDs shown)

This is the best way to do it: Using the court ID.

is there an authoritative source or recommended search pattern to reliably discover the canonical slug?

Yes: https://www.courtlistener.com/help/api/jurisdictions/

This is listed on the main API page under "Available Jurisdictions". Where were you looking for it? Perhaps it needs to be listed in more places.

Preferred discovery flow

Depends what you're doing, but the search engine is a decent way to do it. I'd also highly recommend you look at webhooks if you're thinking about keeping up with a certain query, so you don't have to poll all the time.

Invalid-param errors: you said the upcoming enforcement only disallows incorrect usage — any recommended canonical examples we can use in our test suite to pre-validate requests?

Well, if you're not getting the emails each day, you're good?

We have short logs, sample opinion IDs, and a small test script we can share. If there’s a preferred code snippet (curl/axios) or test case you’d like us to run and post, we can do that and report back.

Curl is usually good, thanks!