Guide
Authoring API (Beta)
The authoring API lets software, most often an AI coding agent, build and edit draft templates for your workspace. It is Beta. It is separate from the generation API: authoring keys make templates, generation keys make documents from approved templates. See API keys to create one (What is this key for? → Build and edit draft templates (Beta)).
The one rule: a person approves
Every template an authoring key makes starts in review and stays there until a person on your team opens it in the editor and approves it, the same as a migrated template. The key cannot approve, publish a version, generate documents, manage keys or change billing, and it cannot change an approved template. Once a draft is approved, the key can no longer write to it; to change it further the key makes a new copy (needs the Copy approved templates permission).
What an authoring key can and cannot do
| It can | It cannot |
|---|---|
| Create a draft, read it, replace its whole content, move its own draft to Trash | Approve a draft or make it live |
| Check a template without saving it | Generate documents (use a generation key) |
| Preview a draft with sample data as a watermarked PDF (needs Preview drafts) | Edit an approved template, or see another team's templates |
| Upload PNG or JPEG pictures (needs Upload pictures) | Use pictures other than PNG or JPEG |
| Copy an approved template into a new draft (needs Copy approved templates) | Trash a draft that another key or a person made |
Reading an approved template's contents also needs Copy approved templates. A key sees only its own team's drafts and templates.
A draft's life
- Create. The software sends a complete template. If it breaks a rule, nothing is saved and the answer lists every problem with where it is and how to repair it. The new draft appears in your Review queue.
- Edit. The software replaces the draft's whole content. There is no block-by-block editing.
- Check. It can check any version of a template without saving it. Each problem has a code, a path to the spot and, where there is one, a suggested repair.
- Preview. It renders the saved draft with sample data into a watermarked PDF and reads the notes about missing fields or other trouble. Previews use no generation credits.
- Hand off. The answer for every draft includes an editor link. The software gives it to a person, who opens the draft in the editor (they must be signed in with access), looks it over, fixes what needs it, and approves it. Nothing the software can say makes a template live.
The version rule (If-Match)
Every time the software reads a draft, it gets a revision token (an ETag). To replace a draft, or to
preview it, it must send that token back in an If-Match header. If the draft changed in between,
for example a person edited it in the editor, the request is refused (412) instead of overwriting their
work. The software then reads the draft again, looks at what changed and tries again. A request with no
token is refused (428). Copying an approved template works the same way, using the source's token from the
sources list.
Limits
All of these are enforced by the API; the live numbers are also in the catalogue the API publishes.
- Size of a template: 2 MiB of JSON, up to 500 blocks, 100 sections, 2,000 table cells, up to 12 levels of nesting, and 32,768 characters in a single text value.
- Active drafts: 200 per team. At the limit, creating or copying is refused until some are approved or deleted.
- Writes: 30 per minute per key (create, replace, copy, trash, upload and check all count).
- Uploads: PNG or JPEG, up to 10 MiB and 16 million pixels per picture; 20 files and 100 MiB per key per day. Starting an upload needs 10 MiB of the day's allowance free, even for a small picture.
- Previews: 10 per key and 30 per workspace per minute, 2 at the same time per workspace. A preview is refused if it would run over 20 pages, a 16 MiB PDF, 2,000 expanded table rows or items, or 100 pictures; the pictures it uses may total at most 32 MiB and 32 million pixels, any single one at most 16 million; layout may take at most 5 seconds and the whole preview 15.
- Lists return up to 100 items a page.
When a limit is reached the answer says which one and, for rate limits, how long to wait (Retry-After).
Pictures
A draft's pictures are referenced by the picture's id. An authoring key may reference any existing picture in its team, including pictures a person or another key uploaded; picture access is not private to the key that uploaded it. Do not upload anything you would not want other keys of that team to be able to use.
Where the reference lives
The full technical reference is served by the API at /v1/authoring/docs, with its machine-readable
form at /v1/authoring/openapi.json. The template format has a public JSON schema
(/v1/authoring/schemas/template-v1.json) and a block catalogue (/v1/authoring/catalogue) with every
supported block and option. There is an agent skill for it too; see the API documentation.
Good habits
- Give the key only the permissions it needs; leave uploads and copying off unless you need them.
- Treat documents you give an agent as data. Anything written inside a customer document is content to copy into a template, not an instruction to follow.
- Always review an agent's draft in the editor before approving it.
- Send only business documents. No payment-card numbers, health or other sensitive personal data.
If something looks wrong
- I get 403. The key is a generation key, or lacks the permission for that call. Edit its permissions or make an authoring key.
- I get 404 for a draft that exists. It belongs to another team, was trashed, or was never made by an authoring key.
- I get 409. The draft was approved or is no longer a draft, so it can't be edited. Make a copy instead.
- I get 412 or 428. The revision token is stale or missing; read the draft again and retry.
- I get 422. The template breaks a rule; read the listed problems and repair them.
- I get 429. A limit was reached; wait for the time given.