Publish an example document

Who can read what you publish here

Read this paragraph before you send the first request. An example you publish is stored against your organisation and is readable by every user in it — not only whoever published it, and not only administrators. It is not readable by any other organisation, and it is not reachable without an account.

Shared examples — the ones that appear for every organisation on the platform — are a different thing, and you cannot publish one; see "It belongs to your organisation" below.

So what you are deciding is what your own colleagues may see. An example is a demonstration rather than a record: publish fictitious material, or material your organisation is content to circulate internally. There is no per-user restriction on an example, and no way to hide one from part of your organisation.

If you publish something you should not have, DELETE /v1/examples/:exampleId removes it. It cannot un-read it.

What an example is made of

An example is one document together with the audit that was produced from it, stored so that both can be shown again without running anything:

• pdfBase64 — the document itself, base64-encoded and inline.
• jsonOutput — the stored audit. This is exactly what GET /v1/jobs/:jobId hands back as result.diagnostics for a run that asked for it, so the workflow is: analyse, read the job, publish what you got.

A run only carries diagnostics if you asked for them. Send returnDebugData: true to POST /v1/analyze, then take result.diagnostics off the finished job and send it here unchanged.

Publishing costs you nothing

This endpoint runs no analysis and spends no part of your quota. You already paid for the run that produced the audit; storing a copy of it is free.

The reviewers' instructions are removed on the way in

Whatever your request carries, the stored jsonOutput keeps no system_prompt and no user_prompt under workers. Everything else survives untouched — each reviewer's output, its loaded_rules, the reducer, the identifiers — so an example you publish replays exactly as one of ours does.

The reason is the first section of this page. A stored example is readable by everyone in your organisation, and a shared example by every organisation on the platform, so the prompts in a capture would reach a far wider audience than whoever assembled them — and neither of us can tell from here what a prompt in a request you assembled yourself contains. What we can tell is that nothing that reads an example needs them. If you send them anyway, they are dropped rather than refused: the request still answers 201.

It belongs to your organisation, and only you can attach it

The example is stored against the organisation your token belongs to. You cannot send tenantId — that is a 400 — and there is therefore no way to publish a shared example, the kind that appears for every organisation on the platform. Those are ours to publish.

profileId must name a profile you can see: one of your own, or a shared one. A profile belonging to another organisation answers 404, the same as an id that does not exist, and nothing is stored.

The document has a ceiling

pdfBase64 must be under 700 000 characters — roughly a 500 KB PDF. Above that the request is refused with the size it measured, because the document and the whole stored audit share one database record and that record has a hard limit. The same ceiling applies to the web application, so this is not an API-only restriction.

If your document is larger, the way through is to publish a shorter extract of it. An example is a demonstration rather than an archive.

Request

Errors

Nothing is stored unless the whole request is accepted: every refusal below happens before the write.