{"openapi":"3.1.0","info":{"title":"CourtListener (BYOK) API","version":"0.1.0","description":"CourtListener (BYOK) lets an AI assistant read your own CourtListener data through the CourtListener API with a key you supply (CourtListener API token). Read-only: 7 tools (search_case_law, search_other_collections, list_dockets, get_docket, get_opinion_cluster, get_opinion, list_citation_links). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-courtlistener.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-courtlistener/docs"},"termsOfService":"https://connectorbay.com/byok-courtlistener/terms"},"servers":[{"url":"https://byok-courtlistener.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-courtlistener/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_case_law":{"post":{"operationId":"search_case_law","summary":"Search U.S. court opinions (case law) by keywords or advanced operators such as caseName:, court_id: or dateFiled:[2020-","description":"Search U.S. court opinions (case law) by keywords or advanced operators such as caseName:, court_id: or dateFiled:[2020-01-01 TO 2024-12-31]. Returns case name, citations, court, filing date, cite count and matching snippets. Only published opinions are included by default; page with cursor. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Find case law about qualified immunity filed since 2020\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search query: plain words, a quoted phrase, or field operators like court_id:scotus.","maxLength":400,"title":"Q","type":"string"},"type":{"anyOf":[{"const":"o","type":"string"},{"type":"null"}],"default":"o","description":"Fixed by this tool; case law opinions.","title":"Type"},"semantic":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to use semantic (plain-language) search instead of keyword search.","title":"Semantic"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the cursor value taken from the next link of the previous answer (leave empty for the first page).","title":"Cursor"}},"required":["q"],"title":"search_case_lawArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_other_collections":{"post":{"operationId":"search_other_collections","summary":"Search CourtListener's other collections with the same query syntax: federal docket filings in PACER (r), PACER document","description":"Search CourtListener's other collections with the same query syntax: federal docket filings in PACER (r), PACER documents (rd), federal dockets (d), judges (p) or oral argument audio (oa). Returns the search engine's own fields, shortened. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Search federal dockets about a company named Acme\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search query: plain words, a quoted phrase, or field operators.","maxLength":400,"title":"Q","type":"string"},"type":{"description":"Collection: r (RECAP dockets with documents), rd (RECAP documents), d (dockets), p (judges) or oa (oral arguments).","enum":["r","rd","d","p","oa"],"title":"Type","type":"string"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the cursor value taken from the next link of the previous answer (leave empty for the first page).","title":"Cursor"}},"required":["q","type"],"title":"search_other_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_dockets":{"post":{"operationId":"list_dockets","summary":"List dockets (case records) filtered by court and docket number, with case name, filing and termination dates, judge nam","description":"List dockets (case records) filtered by court and docket number, with case name, filing and termination dates, judge name and nature of suit. Page with cursor. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Show dockets in the Supreme Court with docket number 23A994\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"court":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Court id, for example scotus, ca9, dcd (get_docket shows court_id values).","title":"Court"},"docket_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Docket number, for example 23A994; add a court because numbers are not unique.","title":"Docket Number"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the cursor value taken from the next link of the previous answer (leave empty for the first page).","title":"Cursor"}},"title":"list_docketsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_docket":{"post":{"operationId":"get_docket","summary":"Get one docket: case name, court, docket number, dates, assigned judge name, cause and nature of suit, and the opinion c","description":"Get one docket: case name, court, docket number, dates, assigned judge name, cause and nature of suit, and the opinion clusters linked to it (no entries, parties or attorneys). Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Show docket 4214664\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"docket_id":{"description":"CourtListener docket id (digits), for example 4214664.","minimum":1,"title":"Docket Id","type":"integer"}},"required":["docket_id"],"title":"get_docketArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_opinion_cluster":{"post":{"operationId":"get_opinion_cluster","summary":"Get one opinion cluster (the grouped decisions of a case; its id is the number in a CourtListener /opinion/<id>/ URL): c","description":"Get one opinion cluster (the grouped decisions of a case; its id is the number in a CourtListener /opinion/<id>/ URL): case name, docket link, citations, judges and the ids of its sub-opinions. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Look up the case with cluster id 2812209 (Obergefell v. Hodges)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cluster_id":{"description":"Cluster id (digits) as in the /opinion/<id>/ page URL or the cluster_id field of search results.","minimum":1,"title":"Cluster Id","type":"integer"}},"required":["cluster_id"],"title":"get_opinion_clusterArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_opinion":{"post":{"operationId":"get_opinion","summary":"Get one opinion: its type (lead, concurrence, dissent ...), original download URL and the text as HTML with linked citat","description":"Get one opinion: its type (lead, concurrence, dissent ...), original download URL and the text as HTML with linked citations. Long opinions are cut off. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Show the text of opinion 9969234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"opinion_id":{"description":"Opinion id (digits), from the sub_opinions list of a cluster or the opinions list of a search result; not the same as a cluster id.","minimum":1,"title":"Opinion Id","type":"integer"}},"required":["opinion_id"],"title":"get_opinionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_citation_links":{"post":{"operationId":"list_citation_links","summary":"List citation links of the case law graph: filter by citing_opinion to see what an opinion cites, or by cited_opinion to","description":"List citation links of the case law graph: filter by citing_opinion to see what an opinion cites, or by cited_opinion to see which later opinions cite it. Each row links two opinion URLs. Page with cursor. Default accounts are limited to 5 requests per minute and 125 per day. Use for \"Which opinions does opinion 2812209 cite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"citing_opinion":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Opinion id whose cited authorities (backward citations) to list.","title":"Citing Opinion"},"cited_opinion":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Opinion id whose later citing opinions (forward citations) to list.","title":"Cited Opinion"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the cursor value taken from the next link of the previous answer (leave empty for the first page).","title":"Cursor"}},"title":"list_citation_linksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}