{"openapi":"3.1.0","info":{"title":"GlobalLawDB API","version":"1.0.0","description":"Versioned, linked law for humans and agents. Text responses use the law-md/1 Markdown profile when Accept: text/markdown."},"servers":[{"url":"/"}],"components":{"schemas":{},"parameters":{}},"paths":{"/v1/resolve":{"post":{"summary":"Resolve citations to stable law:// IDs","description":"Use this first whenever you have a citation string (e.g. 'Companies Act 2006, s 172(1)(f)', '[2023] UKSC 34 [42]', 'SI 2024/123', 'Article 6(1)(f) GDPR', 'point (3) of Article 2 of Directive 2011/83/EU', '32016R0679', '42 U.S.C. § 1983', '40 CFR 60.1', a legislation.gov.uk or ELI URL) or a block of text containing citations. It returns stable law:// IDs that every other tool accepts, plus the in-force status on as_of. Anything listed under Unresolved could not be verified: do not guess an ID, tell the user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"citations":{"type":"array","items":{"type":"string","minLength":2},"maxItems":100,"description":"Citation strings to resolve, up to 100"},"text":{"type":"string","maxLength":50000,"description":"Free text; every citation found in it is resolved"},"jurisdiction_hint":{"type":"array","items":{"type":"string"},"description":"Jurisdiction codes to restrict parsing, e.g. ['uk'], ['eu'], ['us']"},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date for in-force status; default today"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/search":{"post":{"summary":"Search legislation and case law","description":"Search when you do not already have a citation. Matches meaning as well as words, so plain-language questions ('can I cancel an online purchase?') find the provisions that answer them; each hit says whether it matched by keyword, meaning or both. Results are fragments (sections, paragraphs), not whole documents, each with the token cost of reading it in full. Set in_force_on whenever the question concerns a specific date; otherwise only current text is searched. Use within to grep inside one Act or judgment instead of fetching it whole.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2},"jurisdiction":{"type":"array","items":{"type":"string"},"description":"e.g. ['uk','eu','us','fr','de']; law_directory lists them"},"doctype":{"type":"array","items":{"type":"string","enum":["primary_legislation","secondary_legislation","case_law","rule","treaty","guidance","sanctions_designation","bill"]}},"in_force_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"within":{"type":"string","pattern":"^law:\\/\\/","description":"Restrict to one work, e.g. law://uk/ukpga/2006/46"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"offset":{"type":"integer","minimum":0,"default":0}},"required":["query"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/outline":{"post":{"summary":"Table of contents with token counts","description":"Always call this before reading more than one section of a large work. It is cheap and lists the exact fragment IDs that exist on as_of with the token cost of each, so you can pick precisely what to read. Never try to read a whole Act.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^law:\\/\\/","description":"Work or fragment URI"},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"extent":{"type":"string","description":"Territory code: E, W, S, NI (UK), EU, US, or a country's (FR, DE, NO, …)"},"depth":{"type":"integer","minimum":1,"maximum":4,"default":2}},"required":["id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/read":{"post":{"summary":"Read fragments as at a date","description":"Read the text of one or more fragments by stable ID (up to 20 at once). The text is the version in force on as_of; the header line always states that date and extent, quote them when you cite. Use concise unless the user asks about amendment history, commencement or extent; detailed adds inline markers and effect notes. Output is capped by max_tokens and truncated at structural boundaries with the omitted IDs listed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","pattern":"^law:\\/\\/"},"minItems":1,"maxItems":20},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"extent":{"type":"string"},"lang":{"type":"string"},"response_format":{"type":"string","enum":["concise","detailed"],"default":"concise"},"include_children":{"type":"boolean","default":true},"max_tokens":{"type":"integer","minimum":200,"maximum":20000,"default":8000}},"required":["ids"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/diff":{"post":{"summary":"What changed between two dates, and why","description":"Compare a section or Act between two dates. Prefer this over reading both versions yourself. Lists the effects (amending instruments) that came into force in the window, then each changed fragment with word-level {+ +}/{- -} marks.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^law:\\/\\/"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"extent":{"type":"string"},"max_tokens":{"type":"integer","minimum":200,"maximum":20000,"default":8000}},"required":["id","from","to"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/in_force":{"post":{"summary":"Is a provision in force on a date, in a territory?","description":"Check whether provisions apply on a date in a territory. Enacted ≠ in force ≠ applies here: an Act may be passed, not yet commenced, and only extend to England and Wales. Call this before telling a user something applies to them, especially for UK devolved matters. Cheap and bulk (up to 50 IDs).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","pattern":"^law:\\/\\/"},"minItems":1,"maxItems":50},"on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"extent":{"type":"string"}},"required":["ids"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/graph":{"post":{"summary":"Typed relationship neighbourhood","description":"Explore what cites, amends, applies, interprets or overrules a provision or case, and vice versa. For 'is this still good law?' use relations=[overrules,distinguishes,follows], direction=in. For 'what amended this section?' use relations=[amends,repeals], direction=in. Ranked by graph importance where available.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^law:\\/\\/"},"relations":{"type":"array","items":{"type":"string","enum":["cites","amends","repeals","commences","applies","interprets","considers","follows","distinguishes","overrules","implements","supersedes","retains","relates_to","designated_under","same_as"]}},"direction":{"type":"string","enum":["in","out","both"],"default":"both"},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},"required":["id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/timeline":{"post":{"summary":"Versions and effects over time","description":"List every date on which this provision (or Act) changed and what caused it, plus prospective (enacted but not commenced) amendments. Use it to pick as_of values for law_read or law_diff.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^law:\\/\\/"},"extent":{"type":"string"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"include_prospective":{"type":"boolean","default":true}},"required":["id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/sanctions":{"post":{"summary":"Sanctions designations by entity","description":"Find whether a person, company or vessel is designated under a sanctions regime, on a given date, and which regulations authorise it. Matches names, aliases, non-Latin spellings, list IDs (UKSL e.g. RUS0001, OFAC SDN uid e.g. 2674) and IMO numbers with fuzzy matching by default. Each hit carries the designation's law:// ID: pass it to law_read for the full record (identifiers, addresses, statement of reasons), law_timeline for listing history, or law_diff to see what changed between two list publications. Status is as at as_of: 'delisted' means a designation existed but had been removed by then. Coverage: UK Sanctions List (FCDO) and OFAC SDN List (US Treasury). For cross-list identity call law_graph on a designation with relations=[same_as]: candidates carry their evidence (IMO, name + date of birth) and a confidence, and are never merged. Absence from results is not proof of no designation elsewhere.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":300,"description":"Name, alias, list ID or IMO number"},"regimes":{"type":"array","items":{"type":"string"},"description":"Regime name substrings, e.g. ['Russia', 'Belarus']"},"kind":{"type":"string","enum":["individual","organisation","vessel"]},"jurisdiction":{"type":"string","description":"'uk' for the UK Sanctions List, 'us' for OFAC SDN; default all"},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status date; default today"},"include_history":{"type":"boolean","default":false,"description":"Add each hit's listing periods"},"fuzzy":{"type":"boolean","default":true},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/changes":{"post":{"summary":"Delta feed for polling agents","description":"Poll for what changed in the database since your last check (new versions, effects, works). Save next_cursor and pass it back next time. Scope to the work URIs a user cares about to keep responses small.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","description":"ISO timestamp or a next_cursor value"},"work_uris":{"type":"array","items":{"type":"string","pattern":"^law:\\/\\/"}},"limit":{"type":"integer","minimum":1,"maximum":200,"default":50}},"required":["since"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/directory":{"post":{"summary":"Jurisdictions, courts, document types, sources","description":"Find the right codes for jurisdiction filters and learn what is covered, how fresh it is and under which licence. Call once per session when a question spans jurisdictions you have not used yet.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["jurisdictions","courts","doctypes","sources"],"default":"jurisdictions"},"parent":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/define":{"post":{"summary":"Legal definitions of a term","description":"Look up how legislation defines a term ('personal data', 'consumer', 'goods'), as in force on as_of. Returns each defining provision with its law:// ID, the act, and the full defining sentence; exact matches first, then close spellings. Restrict with work (a law:// ID) or jurisdiction ('eu', 'uk', 'us', …). Omit term with a work to list every term that act defines. Prefer this over law_search for 'what does X mean' questions, and quote the definition with its ID.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":2,"maxLength":120},"work":{"type":"string","pattern":"^law:\\/\\/","description":"Limit to one act, e.g. law://eu/reg/2016/679"},"jurisdiction":{"type":"string","description":"'eu', 'uk', 'us', 'fr', …"},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"limit":{"type":"integer","minimum":1,"maximum":200,"default":20}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/facts":{"post":{"summary":"Key facts about an act, case or designation","description":"Structured facts about a work: its dates (made, published, entry into force, application, repeal; designated or delisted for sanctions), makers, topics (EuroVoc, programmes, regimes), identifiers (CELEX, ELI, list IDs) and type-specific detail (legislation form and number; court, parties and judges for cases; list, measures, legal basis, and the subject's identifiers and facts for designations). Use it to answer 'when did X apply from', 'who made it', 'what is it about' without reading the text.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^law:\\/\\/"}},"required":["id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"token_count":{"type":"number"}},"required":["text","token_count"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Bad input"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}}}}