~151 routes179 catalogue entries24 groups41 staff-only

API reference

Every endpoint, grouped by the surface it belongs to. Read the conventions once and the rest of this page is a lookup.

Try it

Composed against mocks, so it works with no credentials. Every outcome is on the menu including the two that are not a number, because those are the two a client gets wrong. Tick the box to point it at a real deployment instead.

Operation

Snippet language

A grounded answer. Returns the standardised contract — including when it declines. Full documentation.

Load an outcome

Response

Run the request to see the response.

cURL — matches the request above

curl -s https://api.taxorch.com/api/v1/tax-assistant/answer \
  -H "Authorization: Bearer $TAXORCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What is the income tax on £60,000 in the UK for 2024/25?","site":1}'

Why the failures are on the menu

Every outcome above is reachable, including the two that are not a number. A playground where every request succeeds trains the one client this API is designed to prevent — the one that renders a figure and treats a refusal as an error.

Conventions

These hold for every endpoint below. They are stated here rather than repeated on each row, because repeating them would make each read as a property of that endpoint rather than of the platform.

Every endpoint is authenticated: There is no anonymous surface. Authentication is a bearer token; a request without one is refused rather than served a reduced result.
Tenant scoping is enforced, not requested: Most endpoints accept ?site=<id> and enforce per-site permission on top of the tenant scope. Queries filter by tenant through a scoped model base, so omitting the parameter narrows what you can see rather than widening it.
Permission is checked by a shared mixin: One mixin gates every endpoint rather than each view deciding for itself. A 403 means the role lacks the permission; the RBAC matrix is published on the trust page.
Every call is audit-logged: Actor, tenant, event type and pinned versions. Refusals are logged separately with their reason, which is what makes refusal rate a measurable metric.
Staff-only surfaces are marked: Corpus, quality, serving and readiness APIs require staff or superuser. A tenant role cannot reach them at all, and they are labelled throughout this reference.
Versioned actions are mirrored: The base prefix is /api/. Versioned actions appear under /api/v1/, and each surface pins its contract version in a response header so a client can detect a breaking change.

41 of the 179 entries require staff or superuser, and 5 whole groups are staff-only: Corpus administration, Quality, evaluation & release gate, AI serving governance, Readiness, RBAC & privacy, Admin review & accuracy. A tenant role receives a 403 from every one of them.

Status codes

Two of these are unusual enough to be worth reading before you write a client, and the last one is not a status code at all — it is the case most clients get wrong.

401: No valid credentials. Not a hint that the resource exists.
403: Authenticated, but the role or the site permission does not allow it. Staff-only surfaces return this to tenant roles.
409: The target record is immutable — a finalised case is the common one. Reopening is a separate, audited action rather than a permitted write.
422: A precondition is unmet, with a blocker list saying exactly which. Not a generic validation failure: it is a list of what to fix.
429: Throttled. Applies to AI generation and question endpoints; the deterministic calculator path is local arithmetic.
200 with an abstention: The important one. An answer the system declined to give is a successful response with verification_status set and no figure — never a 4xx.

Request and response shapes

Every high-risk answer returns the standardised answer contract, documented field by field. That is the shape worth learning, and it is the same whatever endpoint produced it.

Per-endpoint request bodies are not reproduced here. This reference is transcribed from the API surface document, which specifies the contract and the conventions rather than a schema for each of 179 entries — and writing one hundred and seventy-nine plausible schemas would put fiction in the one place you would trust it. Use the typed API for a contract you can generate against:

Typed actions

HTTP

POST /api/v1/tax-assistant/answer
POST /api/v1/tax-assistant/upload
POST /api/v1/tax-assistant/classify
GET  /api/v1/tax-assistant/{id}/status

A note on counting. There are approximately 151 routes, counted from the URL configuration. This catalogue has 179 entries, because some documented rows cover several actions — a ViewSet, or one path with three verbs. The two numbers are different things and this page never uses one for the other.

Try it

Why the failures are on the menu

Conventions

Status codes

Request and response shapes

01Core assistant & calculation

02Coverage, fact interview & deterministic calculation

03Grounded answer engine

04Documents & receipts

05Classification & categories

06Tax returns

07Tax research, memos & notices

08Tax planning & compliance

09Professional cases & workpapers

10Agentic workflows & personalisation

11AI bookkeeper & reports

12Commerce ledger, audit proofs & legislative

13Fraud, anomalies & conversion

14Finance exactness

15Accounting assistant (journal entries)

16Invoices, credit notes & accounting feeds

17Corpus administrationStaff only

18Quality, evaluation & release gateStaff only

19AI serving governanceStaff only

20Readiness, RBAC & privacyStaff only

21Admin review & accuracyStaff only

22Exports & privacy

23Commerce tax configuration

24Versioned typed API

The quickest way to judge this is the API.