Document Generation Overview

Fill Word templates from data product rows over the /v1/doc-gen API: field sheets, proposed sources, drafts, generation batches, and Word and PDF downloads.

The Document Generation API fills Word templates (.docx and .dotx) with the rows of a data product and renders one Word file per row and template, plus a PDF where PDF conversion is available. A template's content controls become its field sheet: a list of named places in the document, each with a source that says where the value comes from. The platform proposes a source for every unconfirmed field, a person confirms it, and from then on the template can be generated against any row of the data product it was proposed for. The endpoints belong to the Document Generation app (catalog slug doc-gen); a workspace uses them after adding the app, and GET /v1/apps lists a workspace's apps by slug.

A field's source has a type that selects its shape: product reads a column of the data product, reference reads a column of the reference table the product's Spec binds, extract reads a value out of a text by pattern, first takes the first non-empty of several sources, case is entered per document, user reads the writer profile of the person behind the key, rule reads a workspace rule by name, today is the current date, party reads an attribute of a contract party by role, variant maps another value to a result with a fallback, condition prints text when a condition holds, fixed is constant text, and lookup chooses among cases with a fallback. A source of no known shape is refused when stored, and a field can be renamed, re-sourced and confirmed but never added: the places a template fills come from the Word file.

Generation has two steps with the same inputs. POST /v1/doc-gen/drafts fills every chosen template for every chosen row on the server and returns, per document, each value with its origin and the fields still missing; nothing is stored. POST /v1/doc-gen/jobs fills the same way and then generates the files as a batch, which runs after the response and is polled with GET /v1/doc-gen/jobs/{id}. Every generated value keeps its origin (the column, the rule, the edit it came from), and the platform fills only the content controls of the Word file, so the output keeps its controls and Word can continue to edit it. The app renders and stores files; it never sends them.

Reads of rows and generated documents follow Sources IAM as the key's minting user (the person who created the key, or the OAuth user). A generated document is readable only by people who may read every source document it was filled from, and batch listings, downloads and archives are filtered the same way. Rules and the writer profile belong to the workspace and to that person respectively. The surface needs a workspace-scoped credential; every route acts on the workspace of the authenticated key.

Authentication and Scopes

Authenticate with Authorization: Bearer $TALONIC_API_KEY. Reads (GET) need the read scope. Every write needs the write scope and the key's person to be a member or above in the workspace; a key minted by a viewer, a key that belongs to no person, and a person who is no longer a member are refused with 403. POST /v1/doc-gen/drafts is the one route that needs only the read scope, because it stores nothing, but as a POST it still requires a member or above behind the key.

• Templates and field sheets: Word Templates and Field Sheet Proposals.
• Inputs of a fill: Data Products & Records and Rules & Writer Profile.
• Output: Generate Documents and Batches & Downloads.
• Worklist: Status & Issues.

Worked Example: Upload, Propose, Confirm, Generate

The Word file travels as base64 inside a JSON body. The body limit is 5 MB, so the Word file can be about 3.7 MB at most.

jq -n --arg b "$(base64 -w0 contract-letter.docx)" \
  '{filename: "contract-letter.docx", content_base64: $b, group: "Letters"}' |
curl -X POST "https://api.talonic.com/v1/doc-gen/templates" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d @-

Then start a proposal against a data product. The run continues after the response, so poll the proposal until its status is done, and confirm the suggested sources.

curl -X POST "https://api.talonic.com/v1/doc-gen/templates/$TEMPLATE_ID/propose" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_product_id": "'$PRODUCT_ID'"}'

curl "https://api.talonic.com/v1/doc-gen/templates/$TEMPLATE_ID/proposal" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl -X POST "https://api.talonic.com/v1/doc-gen/templates/$TEMPLATE_ID/confirm" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Finally, generate. A dry_run first shows which fields would stay empty; the real request is refused with 422 while documents leave fields empty unless allow_missing is true. The response returns the batch while it runs; poll it, then download a document.

curl -X POST "https://api.talonic.com/v1/doc-gen/jobs" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "'$TEMPLATE_ID'",
    "data_product_id": "'$PRODUCT_ID'",
    "record_ids": ["'$RECORD_ID'"]
  }'

curl "https://api.talonic.com/v1/doc-gen/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl -o letter.pdf "https://api.talonic.com/v1/doc-gen/jobs/$JOB_ID/documents/$DOC_ID/file?kind=pdf" \
  -H "Authorization: Bearer $TALONIC_API_KEY"