Documentation

API reference

A REST API over cases, documents, deadlines, drafting, and audit. Every request is scoped to a tenant and every response is filtered by role.

This is an overview of the endpoint surface. Request and response schemas, error codes, and a sandbox tenant are issued with your API credentials — ask through contact sales.

Authentication

Every request carries a bearer token. The token is a JWT whose claims include the tenant identifier and the caller role; both are validated on each request, and the tenant claim is what row-level security keys off. A token that is valid but belongs to another tenant returns an empty result, not a permission error, so that identifiers cannot be probed.

curl https://api.example.com/api/cases \
  -H "Authorization: Bearer $LEGALAI_TOKEN"

Conventions

All requests and responses are JSON, encoded as UTF-8.
Timestamps are ISO 8601 in UTC; dates that carry legal meaning also return the New Zealand local date.
Rate limits are applied per tenant and returned in response headers.
A GET /health endpoint reports service status and requires no authentication.

Cases

A case is the unit everything else hangs off. Case identifiers follow the pattern EC-YYYY-NNNN-env and are carried through every subsequent call.

Method	Path	Description
GET	/api/cases	List cases visible to the caller within their tenant.
POST	/api/cases	Create a case. Returns the assigned case identifier.
GET	/api/cases/:caseId	Fetch a single case with its facts and status.
DELETE	/api/cases/:caseId	Delete a case and its material. Audit entries survive.

Documents and upload

Files are never posted through the API directly. Request a presigned URL, upload to storage, then register the result.

Method	Path	Description
POST	/api/upload/presign-upload	Get a short-lived signed URL for a single file.
POST	/api/upload/presign-download	Get a short-lived signed URL to read a stored file.
GET	/api/documents/:caseId	List documents attached to a case.
GET	/api/documents/:caseId/:documentId	Fetch document metadata and extraction status.
GET	/api/documents/:caseId/:documentId/download	Redirect to a signed download URL.
DELETE	/api/documents/:caseId/:documentId	Remove a document from a case.

Deadlines

Calculations use New Zealand working days and observed public holidays. Responses include the date each period was counted from so the working can be checked.

Method	Path	Description
POST	/api/deadlines/calculate	Calculate procedural deadlines from a set of case dates.
GET	/api/deadlines/holidays/:year	List the public holidays applied for a given year.

Generation

Drafting runs asynchronously. A generation request returns a job; the document appears against the case when the linter and citation validator have both passed.

Method	Path	Description
GET	/api/generation/types	List the document types available to the tenant.
POST	/api/generation/generate	Generate a document of a given type for a case.
POST	/api/generation/statement-of-claim	Generate a statement of claim directly.

Corpus retrieval

Search across statutes and judgments. Statute sources rank ahead of case law, and every result carries the citation needed to verify it.

Method	Path	Description
POST	/api/corpus/search	Search the corpus and return cited passages.
GET	/api/corpus/freshness	Report how recently each source was last ingested.

Audit

The audit log is append-only. Entries record the actor, the case, and the action — not the contents of files.

Method	Path	Description
GET	/api/audit/case/:caseId	Read the audit trail for a case.
GET	/api/audit/export/:caseId	Export a case audit trail for an external reviewer.

Errors

Errors return a JSON body with a stable code, a human-readable message, and the request identifier to quote when asking about it. Validation failures list the offending fields. Nothing in an error body reveals data from another tenant.

Provisioning, roles, and SSO are covered in the tenant setup guide.