API reference

GET/api/documents

List documents

The seeded contracts, plus the caller's own uploads when the request carries a valid cd_anon cookie. The answer depends on the cookie, so it is never cached.

Example

curl 'https://clauses.phoenixcodes.org/api/documents'

Responses

• 200The documents the caller may read.application/json · object
• 500Something failed on the server (internal). Quote the request id.application/json · Error

GET/api/documents/{id}/pdf

Get a document's PDF

The PDF bytes, inline. A seeded contract is cached for an hour; an upload is private, no-store and only its owner can read it.

Parameters

idstringpathrequired

A document id: a slug for a seeded contract (mutual-nda) or u- and a short random id for an upload.

Example

curl 'https://clauses.phoenixcodes.org/api/documents/msa/pdf'

Responses

• 200The PDF.application/pdf · string (application/pdf)
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 500Something failed on the server (internal). Quote the request id.application/json · Error

GET/api/documents/{id}/geometry/{page}

Get a page's text and line boxes

The text of one page and the box of every line, in PDF points with the origin at the top-left. A character range from a citation becomes highlight rectangles with these. Offsets are UTF-16 offsets into text.

Parameters

idstringpathrequired

A document id: a slug for a seeded contract (mutual-nda) or u- and a short random id for an upload.

pageintegerpathrequired

1 to 20001-based page number.

Example

curl 'https://clauses.phoenixcodes.org/api/documents/msa/geometry/%E2%80%A6'

Responses

• 200The page.application/json · PageGeometry
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 500Something failed on the server (internal). Quote the request id.application/json · Error

POST/api/ask

Ask a question about a document

Retrieves clauses from the one document named in the request, and streams an answer that cites them as [p.9 §11.2]. The reply is a server-sent stream in the AI SDK UI message format. Below the confidence threshold no model is called and the stream carries the single sentence Not addressed in this document. with the closest clauses in data-meta.related.

The stream's parts: start; data-meta (confidence first, and again at the end with the model, tokens, cost and timings); data-passages (every passage the model was shown, numbered, with the character ranges a viewer highlights); text-start, text-delta and text-end for the answer; error; finish. A failure after the first token ends the stream with an error part and never splices a second model's answer onto the first.

Each client gets 15 questions per 10 minutes, and the whole demo has a daily token budget that resets at 00:00 UTC.

Request body (JSON)

documentIdstringrequired

The one document to answer from.

questionstringrequired

3 to 500 charactersThe question. Whitespace at either end is trimmed before the length is checked.

sessionIdstring (uuid)

Continue a session. Omit to start one; the id comes back in data-meta.

Example

curl -N -X POST 'https://clauses.phoenixcodes.org/api/ask' \
  -H 'Content-Type: application/json' \
  -d '{"documentId":"msa","question":"What is the cap on each party'\''s liability in a contract year?"}'

Responses

• 200The answer, streamed.text/event-stream · string
• 400The request is not valid. message says which field and why.application/json · Error
• 403A browser sent the request from another site (forbidden). Only this site's own pages may spend the model budget; curl and servers, which send no Origin, are not affected.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 429Too many requests from this client (rate_limited), or too many live uploads (too_many_uploads). Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, a model or the database) is unavailable (upstream_unavailable), or the daily token budget is used up (budget_exhausted, with resetsAt).application/json · Error

POST/api/upload

Upload a PDF

Takes a text PDF of at most 10 MB and 80 pages. The platform caps a request body at 4.5 MB, so the file is sent in parts of at most 4 MB (up to 3), each as the raw body of one request, tied together by x-upload-id. Every part but the last answers 202. The last answers 200 with a stream of newline-delimited JSON progress events, ending in done with the new document, or error.

The upload is private to the caller's cd_anon cookie (set on this response if the caller has none) and deleted after 24 hours. Scanned PDFs, password-protected PDFs and damaged files are refused with a reason; there is no OCR.

Parameters

x-upload-partstringheader

Which part this is, as 2/3. Omit for a file sent in one request.

x-upload-idstringheader

Ties the parts together. Required when there is more than one part.

x-upload-sizeintegerheader

1 to 10485760The whole file's size in bytes. Required when there is more than one part.

x-upload-namestringheader

The file's name, used for the title when the PDF has none.

Request body

application/pdf: The raw bytes of one part, at most 4,000,000.

Example

curl -N -X POST 'https://clauses.phoenixcodes.org/api/upload' \
  -H 'x-upload-part: 1/3' \
  -H 'x-upload-id: 7f3a9c1e-5b2d' \
  -H 'x-upload-size: 9200000' \
  -H 'Content-Type: application/pdf' \
  --data-binary @contract.pdf

Responses

• 200Progress events, one JSON object per line, ending in done or error.application/x-ndjson · UploadEvent
• 202A part before the last was stored.application/json · object
• 400The request is not valid. message says which field and why.application/json · Error
• 403A browser sent the request from another site (forbidden). Only this site's own pages may spend the model budget; curl and servers, which send no Origin, are not affected.application/json · Error
• 413A part or the whole file is over the limit (payload_too_large).application/json · Error
• 415The body is not sent as application/pdf (unsupported_media_type).application/json · Error
• 422The first bytes are not a PDF's (not_a_pdf).application/json · Error
• 429Too many requests from this client (rate_limited), or too many live uploads (too_many_uploads). Wait retryAfterSeconds.application/json · Error

GET/api/compare

Compare two documents

Aligns the clauses of two documents by text, heading and number, so a renumbered or dropped article still pairs, and returns the word-level diff of each pair, the list of changes and any saved one-line summaries. The result is rebuilt on every request; only the model-written summaries are stored. Both documents must be readable by the caller.

Parameters

leftstringqueryrequired

The earlier document's id.

rightstringqueryrequired

The later document's id. Must differ from left.

Example

curl 'https://clauses.phoenixcodes.org/api/compare?left=mutual-nda&right=mutual-nda-v2'

Responses

• 200The comparison.application/json · Comparison
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 503A dependency (search, a model or the database) is unavailable (upstream_unavailable), or the daily token budget is used up (budget_exhausted, with resetsAt).application/json · Error

POST/api/compare/gloss

Write the one-line summaries of a comparison

Has a model write one sentence per change, once, and saves them for the pair. A sentence that mentions a number the change does not contain is dropped. Nothing is charged to the rate limit or the budget when the summaries already exist or no model is configured. 8 summary requests per 10 minutes per client.

Request body (JSON)

leftstringrequired

The earlier document's id.

rightstringrequired

The later document's id.

Example

curl -X POST 'https://clauses.phoenixcodes.org/api/compare/gloss' \
  -H 'Content-Type: application/json' \
  -d '{"left":"mutual-nda","right":"mutual-nda-v2"}'

Responses

• 200The comparison with its summaries, and how many were newly written.application/json · Comparison
• 400The request is not valid. message says which field and why.application/json · Error
• 403A browser sent the request from another site (forbidden). Only this site's own pages may spend the model budget; curl and servers, which send no Origin, are not affected.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 429Too many requests from this client (rate_limited), or too many live uploads (too_many_uploads). Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, a model or the database) is unavailable (upstream_unavailable), or the daily token budget is used up (budget_exhausted, with resetsAt).application/json · Error

GET/api/sessions/{id}/export

Export a question session

The questions and answers of one session with every citation kept: Markdown with GitHub footnotes, or an A4 PDF typeset in the site's type and colours with the citations as footnotes. Only the visitor who asked the questions can export them; anyone else gets 404. 10 exports per 10 minutes per client.

Parameters

idstring (uuid)pathrequired

The session id, from data-meta.sessionId in an ask stream.

format"pdf" | "md"query

default "pdf"The file format.

Example

curl 'https://clauses.phoenixcodes.org/api/sessions/%E2%80%A6/export'

Responses

• 200The export, as an attachment. Never cached.application/pdf · string (application/pdf)text/markdown · string
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 429Too many requests from this client (rate_limited), or too many live uploads (too_many_uploads). Wait retryAfterSeconds.application/json · Error

GET/api/eval/runs

List eval runs

Stored scorecards from pnpm eval, newest first, without the per-question results. A run with retrievalOnly: true measured retrieval and the confidence gate but had no answer model, so its answer figures are null rather than zero.

Parameters

limitintegerquery

1 to 50 · default 10How many runs to return.

Example

curl 'https://clauses.phoenixcodes.org/api/eval/runs'

Responses

• 200The runs.application/json · object
• 400The request is not valid. message says which field and why.application/json · Error
• 503A dependency (search, a model or the database) is unavailable (upstream_unavailable), or the daily token budget is used up (budget_exhausted, with resetsAt).application/json · Error

GET/api/eval/runs/{id}

Get one eval run

One stored run with the result of every question.

Parameters

idstring (uuid)pathrequired

The run id.

Example

curl 'https://clauses.phoenixcodes.org/api/eval/runs/%E2%80%A6'

Responses

• 200The run and its questions.application/json · EvalRunDetail
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no such document, page, session or run, or it belongs to another visitor. The two cases look the same on purpose.application/json · Error
• 503A dependency (search, a model or the database) is unavailable (upstream_unavailable), or the daily token budget is used up (budget_exhausted, with resetsAt).application/json · Error

GET/api/cron/purge

Delete expired uploads

Called once a day by the platform's scheduler, which sends Authorization: Bearer <CRON_SECRET>. Deletes uploads past their 24 hours and abandoned upload parts. Without the secret the answer is 401. Reads of an expired upload are refused whether or not this has run; the sweep reclaims space.

Example

curl 'https://clauses.phoenixcodes.org/api/cron/purge' \
  -H 'Authorization: Bearer $CRON_SECRET'

Responses

• 200How many uploads were removed.application/json · object
• 401The bearer secret is missing or wrong.application/json · Error
• 500Something failed on the server (internal). Quote the request id.application/json · Error

Schemas

The shapes the routes above send and return. AskMeta and Passage travel inside the ask stream as the data-meta and data-passages parts.