search_law
Instruments matching a query, in a jurisdiction, in force on a date.
required: q
One declaration, three surfaces
Every capability below is declared once and rendered as a REST route, an MCP tool and this page. Hand-listing them three times is how an endpoint ends up exposed over MCP with different argument names — or exposed over REST and forgotten over MCP, which is worse because nobody notices until a customer does.
Authentication
A bearer token on every request. Keys are minted per organisation and carry scopes; a key with no scopes authenticates and does nothing.
curl https://incredibleattorneys.com/api/v1/law?q=employment \ -H "Authorization: Bearer ia_..."
ai.summarizeatlas.readbookings.readbookings.writecases.readconnect.writecourt.readdirectory.readdocuments.readgraph.readlaw.readlawpulse.readlawtag.readlawtag.writemarketplace.readmatters.readmatters.writenotes.readresearch.readsanctions.readstats.readtools.readwebhooks.write
REST
| Endpoint | Scope | What it does |
|---|---|---|
| GET /api/v1/law | law.read | Instruments matching a query, in a jurisdiction, in force on a date. |
| GET /api/v1/law/:id | law.read | One instrument, with the version that was in force on the date asked about. |
| GET /api/v1/cases | cases.read | Decisions matching a query, with their treatment. |
| GET /api/v1/cases/:id/treatment | cases.read | Subsequent treatment from the citation graph. `unknown_treatment` means nothing cites it — not that it is undisturbed. |
| GET /api/v1/constitutions/compare | law.read | The provisions themselves, side by side. Never a ranking. |
| GET /api/v1/jurisdictions/:code | law.read | A jurisdiction with every jurisdiction it inherits law from. |
| GET /api/v1/taxonomy/search | law.read | Turn a lay description into ontology nodes. "I was fired" → wrongful termination. |
| POST /api/v1/ask | research.read | Returns an evidence chain: the authorities, their dates, a support verdict and any warnings. Refuses rather than guessing. |
| GET /api/v1/knowledge | law.read | Passages from legislation, cases and guidance, as numbered text blocks that each name their source. Built for assistants such as Agent Law to ground an answer. |
| GET /api/v1/attorneys | directory.read | Published practitioners matching factual filters, in a stable public shape (never contact details). The platform publishes no quality ranking; ties are shuffled. |
| GET /api/v1/attorneys/:id | directory.read | One published practitioner (public shape) with their listed services. |
| GET /api/v1/services | marketplace.read | Listed fixed-fee services of published practitioners, with what each fee excludes. |
| POST /api/v1/bookings | bookings.write | Ask a practitioner for a consultation at one of the client's preferred times. It reaches the practitioner's IA inbox; they accept a preferred time, propose another, quote or decline (webhook booking.updated). Refused when they are not accepting. With a connection (X-IA-Grant / grant) the booking is made for that IA account. |
| GET /api/v1/bookings/:id | bookings.read | One of this key's organization's bookings: status, time, quote, room. |
| GET /api/v1/bookings | bookings.read | This key's organization's bookings, newest first; by client external_ref, status or connection. |
| POST /api/v1/bookings/:id/cancel | bookings.write | The client no longer wants it. The practitioner is told in their inbox. |
| POST /api/v1/bookings/:id/confirm | bookings.write | The client accepts the time the practitioner proposed, or their quote: the booking is accepted. |
| POST /api/v1/bookings/:id/join | bookings.write | A two-minute Telenaas grant for the booking's client to join the video or call room natively (socket_url, token, topic, room_id, publish). Only once the practitioner opened the room; only for the booking's client. |
| POST /api/v1/webhooks | webhooks.write | Where booking.updated, connect_request.* and connection.revoked are sent, signed x-ia-signature: t=…,v1=HMAC-SHA256(secret, "t.body"). Replaces the previous URL; the secret is returned once. |
| GET /api/v1/webhooks | webhooks.write | The active webhook endpoint, with its last delivery status. Never the secret. |
| POST /api/v1/connect/token | connect.write | After the IA app handed your app a code (incredibleattorneys://connect … → <return>?code=…), exchange it with the PKCE verifier for a revocable grant (iag_…, returned once). |
| POST /api/v1/connect/requests | connect.write | When the IA app is not on this device: the person approves in their IA app, or types the 6-digit code they were sent into your screen. The answer is the same whether or not the person exists. |
| GET /api/v1/connect/requests/:id | connect.write | Poll a request. The first poll after an in-app approval carries the connection with its grant, once. |
| POST /api/v1/connect/requests/:id/complete | connect.write | The 6-digit code the person typed into your screen; returns the connection with its grant. Five wrong codes lock the request. |
| GET /api/v1/connect/grant | connect.write | The connection behind a grant (status, scopes, account). 401 grant_revoked once revoked. |
| POST /api/v1/connect/revoke | connect.write | Revoke a connection by its grant or its connection_id. Idempotent. |
| GET /api/v1/changes | lawpulse.read | New instruments, amendments, repeals, commencements and judgments. |
| GET /api/v1/stats/indicators | stats.read | Indicator definitions — type, unit, kind of evidence, whether underreported — optionally for one topic. Definitions, never a composite score. |
| GET /api/v1/stats/indicators/:code | stats.read | One indicator's values for up to six countries, each with year, status and source attribution. |
| GET /api/v1/stats/indicators/:code/latest | stats.read | The latest value in every country that publishes one. Sorted by name — not a league table. |
| GET /api/v1/stats/countries/:iso2 | stats.read | Every indicator for one country, with or without data, so gaps are as visible as numbers. |
| GET /api/v1/atlas/lenses | atlas.read | Every domain, its family, its data status (live, derived, reference, framework) and its sources. |
| GET /api/v1/atlas/lenses/:code | atlas.read | A domain's law, cases, statistics, records, findings, events and stated gaps, optionally for one country. |
| GET /api/v1/atlas/entries | atlas.read | Rights, treaties, procedures, obligations and other records, each with its source and review status. |
| GET /api/v1/atlas/entries/:id | atlas.read | A record with its steps, findings (with attribution and standing) and provenance. |
| GET /api/v1/sanctions/screen | sanctions.read | Similar names on the UN Security Council and OFAC SDN lists, with each list's publication date. A match is not a determination. |
| GET /api/v1/companies | atlas.read | Entities by name from GLEIF, live. |
| GET /api/v1/companies/:lei | atlas.read | One entity by LEI with its reported direct and ultimate parents, or GLEIF's reporting exception. |
| GET /api/v1/countries/:iso2/treaties | atlas.read | Signature and ratification, accession or succession dates, from the depositary. |
| GET /api/v1/countries/:iso2/landscape | atlas.read | Constitution, law, courts, treaties, statistics and recent changes for a country — and what is missing. |
| GET /api/v1/law-watch | lawpulse.read | Changes derived from instrument dates, plus LawPulse's detected changes; `upcoming` for what has not commenced yet. |
| GET /api/v1/graph/nodes | graph.read | Public graph nodes whose label matches. |
| GET /api/v1/graph/nodes/:id/neighbours | graph.read | Edges with their relation and who asserted them (official, editorial, parser). |
| POST /api/v1/tools/intestacy | tools.read | Applies a documented statutory rule set (England & Wales) to the family described, with every assumption and provision. Refuses for rules not encoded. Not advice. |
| GET /api/v1/tools/patient-rights/:country | tools.read | Patient rights with their authority, linked where the corpus holds it. |
| GET /api/v1/atlas/coverage | atlas.read | Legislation, decisions, records and indicators with data, per domain — LawGap as data. |
| GET /api/v1/court/hearings | court.read | Hearings a court has authorised for public access: live, starting soon, today and tomorrow. |
| GET /api/v1/court/hearings/:slug | court.read | A public hearing's status, public timeline, court rule and published documents. Not the official record. |
| GET /api/v1/assist/read/:type/:id | law.read | A case, statute, constitution, atlas record, document or NoteTaker session as ordered sections with anchors and citable pinpoints — what the Narrator reads and summaries cite. |
| POST /api/v1/assist/summarize | ai.summarize | A summary in one of five modes (executive, lawyer, citizen, reporter, court). Every statement is labelled fact/law/analysis/opinion and cites the pinpoints it rests on; a long text states which part was read. Refuses when no model is configured. |
| GET /api/v1/cases/:id/intelligence | law.read | Parties, issues, positions and responses, evidence, witnesses, reasoning, outcome, remedies, timeline, authorities and appeal status — each item with its provenance (stated, derived, ai_structured) and the paragraphs it rests on. The outcome is null when not established. |
| POST /api/v1/cases/:id/intelligence | ai.summarize | Extract the AI-structured layer for a judgment (once per version of its text). Every item must cite a paragraph that exists; quotations are checked word for word. |
| GET /api/v1/lawtag/team | lawtag.read | The LawTAG team members this key's person can @mention: handle, purpose, jurisdictions and what each may read. |
| POST /api/v1/lawtag/ask | lawtag.write | Post a message that @mentions LawTAGs; each answers in turn from what it may read. Returns their statements with evidence. Needs a key issued to a person. |
| POST /api/v1/notes/ask | notes.read | An answer from the key person's NoteTaker transcripts and kept notes, each statement citing a transcript timestamp. Refuses when nothing matches. |
| GET /api/v1/cases/:id | cases.read | One decision: citation, court, date, judges, parties, outcome, holding, and its citation in the jurisdiction's style. |
| GET /api/v1/courts | cases.read | Courts in the directory, optionally by country or name. |
| GET /api/v1/courts/:slug | cases.read | A court with its latest judgments in the corpus, the judges they name, and public hearings. |
| GET /api/v1/judges | cases.read | Judges named in published judgments, with how many name them. Facts, never ratings. |
| GET /api/v1/judges/:slug | cases.read | A judge's profile from the judgments naming them: courts, dates, subjects, outcomes as recorded, recent judgments. |
| GET /api/v1/jurisdictions | law.read | Every country the platform models, with ISO codes and legal families. |
| GET /api/v1/cite | law.read | A citation in OSCOLA, Bluebook, McGill, AGLC, EU or generic style, built only from fields held; `missing` names what a full citation needs that is not held. |
| GET /api/v1/law/:id/explain | law.read | A provision's record (effective date, jurisdiction, official source, interpreting cases, definitions it uses) and, when a model is configured, a cited explanation. |
| GET /api/v1/law/:id/changes | law.read | Two versions of an instrument compared provision by provision, with the values that moved; without from/to, each version against the one before. |
| GET /api/v1/help/rights | atlas.read | Rights, procedures, remedies and time limits possibly relevant to an area of law in a country, each with its source. Never a determination. |
| GET /api/v1/legal-aid | atlas.read | Official legal aid authorities, public defenders and eligibility checkers, with their official sites. |
| GET /api/v1/legal-aid/providers | atlas.read | Offices holding a legal aid contract near a UK postcode, live from the Legal Aid Agency, nearest first. |
| POST /api/v1/help/intake | atlas.read | From a person's account: possible legal areas, documents to gather, time limits to check, authorities, rights, legal aid, practitioners and questions to ask. Not stored; never a verdict. |
| GET /api/v1/human-rights/incidents | atlas.read | Court decisions engaging human-rights claims, by category and country — decisions to review, not findings of violation. |
| GET /api/v1/observatory/justice | stats.read | The latest held figure for courts, police, prisons and legal aid indicators across countries, each with period and source; null where none is held. |
| POST /api/v1/news-to-law | cases.read | From an article's text to the primary sources: the cases, judgments, law, previous cases and areas it names, matched to the corpus. Nothing is fetched. |
| GET /api/v1/tools/consent-guidance/:country | tools.read | The patient rights that bear on consent, capacity, refusal and health records in a country, each with its authority (linked where the corpus holds it), plus the consent-form starters that fit. Legal information, not advice; refuses for countries with no encoded card. |
| GET /api/v1/documents/templates | documents.read | The platform's starter templates (consent forms and similar) and the organisation's own templates, each with the placeholders it needs. Starters are unreviewed drafts. |
| POST /api/v1/documents/draft | documents.read | Fills a template's {{placeholders}} and returns the text, leaving anything not supplied visibly unfilled and listing it. Nothing is stored. A draft for review, never a final document. |
| GET /api/v1/matters | matters.read | The key's organisation's matters, newest first, honouring ethical walls. |
| GET /api/v1/matters/:id | matters.read | One matter with its client and its deadlines, soonest first, each with its basis. |
| POST /api/v1/matters | matters.write | Records a new matter at intake (not opened, nothing billable) with its client, in the key's organisation. Without confirm: true it only returns what would be created. |
| GET /api/v1/coverage | law.read | Corpus counts per jurisdiction, so an integrator can tell an empty answer from a gap in coverage. |
MCP tools
Point an MCP client at POST /mcp. The tool definitions below are derived from the same catalogue as the REST routes.
get_instrument
One instrument, with the version that was in force on the date asked about.
required: id
search_cases
Decisions matching a query, with their treatment.
required: q
case_treatment
Subsequent treatment from the citation graph. `unknown_treatment` means nothing cites it — not that it is undisturbed.
required: id
compare_constitutions
The provisions themselves, side by side. Never a ranking.
required: topic, countries
resolve_jurisdiction
A jurisdiction with every jurisdiction it inherits law from.
required: code
classify_subject
Turn a lay description into ontology nodes. "I was fired" → wrongful termination.
required: q
ask
Returns an evidence chain: the authorities, their dates, a support verdict and any warnings. Refuses rather than guessing.
required: question, jurisdiction
search_knowledge
Passages from legislation, cases and guidance, as numbered text blocks that each name their source. Built for assistants such as Agent Law to ground an answer.
required: query
find_practitioners
Published practitioners matching factual filters, in a stable public shape (never contact details). The platform publishes no quality ranking; ties are shuffled.
get_practitioner
One published practitioner (public shape) with their listed services.
required: id
browse_services
Listed fixed-fee services of published practitioners, with what each fee excludes.
book_consultation
Ask a practitioner for a consultation at one of the client's preferred times. It reaches the practitioner's IA inbox; they accept a preferred time, propose another, quote or decline (webhook booking.updated). Refused when they are not accepting. With a connection (X-IA-Grant / grant) the booking is made for that IA account.
required: channel, summary, preferred_times
get_booking
One of this key's organization's bookings: status, time, quote, room.
required: id
list_bookings
This key's organization's bookings, newest first; by client external_ref, status or connection.
cancel_booking
The client no longer wants it. The practitioner is told in their inbox.
required: id
confirm_booking
The client accepts the time the practitioner proposed, or their quote: the booking is accepted.
required: id
join_booking
A two-minute Telenaas grant for the booking's client to join the video or call room natively (socket_url, token, topic, room_id, publish). Only once the practitioner opened the room; only for the booking's client.
required: id
register_webhook
Where booking.updated, connect_request.* and connection.revoked are sent, signed x-ia-signature: t=…,v1=HMAC-SHA256(secret, "t.body"). Replaces the previous URL; the secret is returned once.
required: url
list_webhooks
The active webhook endpoint, with its last delivery status. Never the secret.
connect_exchange_code
After the IA app handed your app a code (incredibleattorneys://connect … → <return>?code=…), exchange it with the PKCE verifier for a revocable grant (iag_…, returned once).
required: code, code_verifier
connect_request
When the IA app is not on this device: the person approves in their IA app, or types the 6-digit code they were sent into your screen. The answer is the same whether or not the person exists.
connect_request_status
Poll a request. The first poll after an in-app approval carries the connection with its grant, once.
required: id
connect_complete
The 6-digit code the person typed into your screen; returns the connection with its grant. Five wrong codes lock the request.
required: code, id
connect_grant
The connection behind a grant (status, scopes, account). 401 grant_revoked once revoked.
connect_revoke
Revoke a connection by its grant or its connection_id. Idempotent.
law_changes
New instruments, amendments, repeals, commencements and judgments.
stats_indicators
Indicator definitions — type, unit, kind of evidence, whether underreported — optionally for one topic. Definitions, never a composite score.
stats_series
One indicator's values for up to six countries, each with year, status and source attribution.
required: code
stats_latest
The latest value in every country that publishes one. Sorted by name — not a league table.
required: code
stats_country
Every indicator for one country, with or without data, so gaps are as visible as numbers.
required: iso2
atlas_lenses
Every domain, its family, its data status (live, derived, reference, framework) and its sources.
atlas_lens
A domain's law, cases, statistics, records, findings, events and stated gaps, optionally for one country.
required: code
atlas_entries
Rights, treaties, procedures, obligations and other records, each with its source and review status.
atlas_entry
A record with its steps, findings (with attribution and standing) and provenance.
required: id
sanctions_screen
Similar names on the UN Security Council and OFAC SDN lists, with each list's publication date. A match is not a determination.
required: name
company_search
Entities by name from GLEIF, live.
required: q
company
One entity by LEI with its reported direct and ultimate parents, or GLEIF's reporting exception.
required: lei
country_treaties
Signature and ratification, accession or succession dates, from the depositary.
required: iso2
legal_landscape
Constitution, law, courts, treaties, statistics and recent changes for a country — and what is missing.
required: iso2
law_watch
Changes derived from instrument dates, plus LawPulse's detected changes; `upcoming` for what has not commenced yet.
graph_search
Public graph nodes whose label matches.
required: q
graph_neighbours
Edges with their relation and who asserted them (official, editorial, parser).
required: id
intestacy
Applies a documented statutory rule set (England & Wales) to the family described, with every assumption and provision. Refuses for rules not encoded. Not advice.
required: died_on
patient_rights
Patient rights with their authority, linked where the corpus holds it.
required: country
atlas_coverage
Legislation, decisions, records and indicators with data, per domain — LawGap as data.
court_calendar
Hearings a court has authorised for public access: live, starting soon, today and tomorrow.
court_hearing
A public hearing's status, public timeline, court rule and published documents. Not the official record.
required: slug
readable
A case, statute, constitution, atlas record, document or NoteTaker session as ordered sections with anchors and citable pinpoints — what the Narrator reads and summaries cite.
required: id, type
summarize
A summary in one of five modes (executive, lawyer, citizen, reporter, court). Every statement is labelled fact/law/analysis/opinion and cites the pinpoints it rests on; a long text states which part was read. Refuses when no model is configured.
required: id, type, mode
case_intelligence
Parties, issues, positions and responses, evidence, witnesses, reasoning, outcome, remedies, timeline, authorities and appeal status — each item with its provenance (stated, derived, ai_structured) and the paragraphs it rests on. The outcome is null when not established.
required: id
structure_case
Extract the AI-structured layer for a judgment (once per version of its text). Every item must cite a paragraph that exists; quotations are checked word for word.
required: id
lawtag_team
The LawTAG team members this key's person can @mention: handle, purpose, jurisdictions and what each may read.
lawtag_ask
Post a message that @mentions LawTAGs; each answers in turn from what it may read. Returns their statements with evidence. Needs a key issued to a person.
required: message
notes_ask
An answer from the key person's NoteTaker transcripts and kept notes, each statement citing a transcript timestamp. Refuses when nothing matches.
required: question
get_case
One decision: citation, court, date, judges, parties, outcome, holding, and its citation in the jurisdiction's style.
required: id
list_courts
Courts in the directory, optionally by country or name.
get_court
A court with its latest judgments in the corpus, the judges they name, and public hearings.
required: slug
list_judges
Judges named in published judgments, with how many name them. Facts, never ratings.
get_judge
A judge's profile from the judgments naming them: courts, dates, subjects, outcomes as recorded, recent judgments.
required: slug
list_jurisdictions
Every country the platform models, with ISO codes and legal families.
cite
A citation in OSCOLA, Bluebook, McGill, AGLC, EU or generic style, built only from fields held; `missing` names what a full citation needs that is not held.
required: id, type
explain_provision
A provision's record (effective date, jurisdiction, official source, interpreting cases, definitions it uses) and, when a model is configured, a cited explanation.
required: id, path
law_changes_between
Two versions of an instrument compared provision by provision, with the values that moved; without from/to, each version against the one before.
required: id
rights_check
Rights, procedures, remedies and time limits possibly relevant to an area of law in a country, each with its source. Never a determination.
required: area
legal_aid
Official legal aid authorities, public defenders and eligibility checkers, with their official sites.
legal_aid_providers
Offices holding a legal aid contract near a UK postcode, live from the Legal Aid Agency, nearest first.
required: postcode
intake
From a person's account: possible legal areas, documents to gather, time limits to check, authorities, rights, legal aid, practitioners and questions to ask. Not stored; never a verdict.
required: what
rights_incidents
Court decisions engaging human-rights claims, by category and country — decisions to review, not findings of violation.
justice_transparency
The latest held figure for courts, police, prisons and legal aid indicators across countries, each with period and source; null where none is held.
required: countries
news_to_law
From an article's text to the primary sources: the cases, judgments, law, previous cases and areas it names, matched to the corpus. Nothing is fetched.
required: text
consent_guidance
The patient rights that bear on consent, capacity, refusal and health records in a country, each with its authority (linked where the corpus holds it), plus the consent-form starters that fit. Legal information, not advice; refuses for countries with no encoded card.
required: country
document_templates
The platform's starter templates (consent forms and similar) and the organisation's own templates, each with the placeholders it needs. Starters are unreviewed drafts.
draft_document
Fills a template's {{placeholders}} and returns the text, leaving anything not supplied visibly unfilled and listing it. Nothing is stored. A draft for review, never a final document.
required: template
list_matters
The key's organisation's matters, newest first, honouring ethical walls.
get_matter
One matter with its client and its deadlines, soonest first, each with its basis.
required: id
create_matter
Records a new matter at intake (not opened, nothing billable) with its client, in the key's organisation. Without confirm: true it only returns what would be created.
required: title, client_name
coverage
Corpus counts per jurisdiction, so an integrator can tell an empty answer from a gap in coverage.
What the API promises
An empty result is explained
Responses distinguish "we hold no registered source for this jurisdiction" from "nothing matched your query". Use /coverage before trusting an empty answer.
Answers carry their authority
/ask returns an evidence chain and a support verdict, not prose. A verdict below partially_supported means the platform declined to answer.
Everything is dated
Pass as_at to ask what the law was. Omit it and you get today. There is no third option, and no silent default to "latest".
Jurisdiction is required where it matters
/ask will not answer without one. Law differs between jurisdictions, and an answer from the wrong one is not a worse answer — it is the wrong law.