Render a template

POST

/v1/render

curl -H "X-Api-Key: $KEY" -F template=@invoice.docx -F 'data=<invoice.json' \
  -F steps=convert http://localhost:9027/v1/render -o invoice.pdf

import { openAsBlob } from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('template', await openAsBlob('invoice.docx'), 'invoice.docx');
form.append('data', await readFile('invoice.json', 'utf8'));
form.append('steps', 'convert');

const response = await fetch('http://localhost:9027/v1/render', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.KEY },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
await writeFile('invoice.pdf', Buffer.from(await response.arrayBuffer()));

import os
from pathlib import Path

import requests

response = requests.post(
    "http://localhost:9027/v1/render",
    headers={"X-Api-Key": os.environ["KEY"]},
    files=[("template", open("invoice.docx", "rb"))],
    data={"data": Path("invoice.json").read_text(), "steps": "convert"},
)
response.raise_for_status()
Path("invoice.pdf").write_bytes(response.content)

package main

import (
  "bytes"
  "io"
  "log"
  "mime/multipart"
  "net/http"
  "os"
  "path/filepath"
)

func main() {
  var body bytes.Buffer
  form := multipart.NewWriter(&body)
  attach(form, "template", "invoice.docx")
  data, err := os.ReadFile("invoice.json")
  if err != nil {
    log.Fatal(err)
  }
  form.WriteField("data", string(data))
  form.WriteField("steps", "convert")
  form.Close()

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/render", &body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("Content-Type", form.FormDataContentType())

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }

  out, err := os.Create("invoice.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer out.Close()
  if _, err := io.Copy(out, response.Body); err != nil {
    log.Fatal(err)
  }
}

// attach adds the file at path to the form as the named field.
func attach(form *multipart.Writer, field, path string) {
  file, err := os.Open(path)
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()
  part, err := form.CreateFormFile(field, filepath.Base(path))
  if err != nil {
    log.Fatal(err)
  }
  if _, err := io.Copy(part, file); err != nil {
    log.Fatal(err)
  }
}

curl -H "X-Api-Key: $KEY" -H "Content-Type: application/json" -d '{
    "templateId": "invoice",
    "data": {"customer":{"name":"Ada"},"total":1500},
    "steps": ["convert"]
  }' http://localhost:9027/v1/render -o invoice.pdf

import { writeFile } from 'node:fs/promises';

const response = await fetch('http://localhost:9027/v1/render', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'invoice',
    data: { customer: { name: 'Ada' }, total: 1500 },
    steps: ['convert'],
  }),
});
if (!response.ok) throw new Error(await response.text());
await writeFile('invoice.pdf', Buffer.from(await response.arrayBuffer()));

import os
from pathlib import Path

import requests

response = requests.post(
    "http://localhost:9027/v1/render",
    headers={"X-Api-Key": os.environ["KEY"]},
    json={
        "templateId": "invoice",
        "data": {"customer": {"name": "Ada"}, "total": 1500},
        "steps": ["convert"],
    },
)
response.raise_for_status()
Path("invoice.pdf").write_bytes(response.content)

package main

import (
  "io"
  "log"
  "net/http"
  "os"
  "strings"
)

func main() {
  body := strings.NewReader(`{
  "templateId": "invoice",
  "data": {
    "customer": {
      "name": "Ada"
    },
    "total": 1500
  },
  "steps": [
    "convert"
  ]
}`)

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/render", body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("Content-Type", "application/json")

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }

  out, err := os.Create("invoice.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer out.Close()
  if _, err := io.Copy(out, response.Body); err != nil {
    log.Fatal(err)
  }
}

import { openAsBlob } from 'node:fs';
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('template', await openAsBlob('invoice.docx'), 'invoice.docx');
form.append('data', await readFile('invoice.json', 'utf8'));
form.append('steps', 'convert');

const response = await fetch('http://localhost:9027/v1/render', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.KEY, Prefer: 'respond-async' },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

import os
from pathlib import Path

import requests

response = requests.post(
    "http://localhost:9027/v1/render",
    headers={"X-Api-Key": os.environ["KEY"], "Prefer": "respond-async"},
    files=[("template", open("invoice.docx", "rb"))],
    data={"data": Path("invoice.json").read_text(), "steps": "convert"},
)
response.raise_for_status()
print(response.json())

package main

import (
  "bytes"
  "io"
  "log"
  "mime/multipart"
  "net/http"
  "os"
  "path/filepath"
)

func main() {
  var body bytes.Buffer
  form := multipart.NewWriter(&body)
  attach(form, "template", "invoice.docx")
  data, err := os.ReadFile("invoice.json")
  if err != nil {
    log.Fatal(err)
  }
  form.WriteField("data", string(data))
  form.WriteField("steps", "convert")
  form.Close()

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/render", &body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("Prefer", "respond-async")
  request.Header.Set("Content-Type", form.FormDataContentType())

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }
  if _, err := io.Copy(os.Stdout, response.Body); err != nil {
    log.Fatal(err)
  }
}

// attach adds the file at path to the form as the named field.
func attach(form *multipart.Writer, field, path string) {
  file, err := os.Open(path)
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()
  part, err := form.CreateFormFile(field, filepath.Base(path))
  if err != nil {
    log.Fatal(err)
  }
  if _, err := io.Copy(part, file); err != nil {
    log.Fatal(err)
  }
}

curl -H "X-Api-Key: $KEY" \
  -H "X-Rusticdoc-Webhook-Url: https://receiver.example.com/documents" \
  -F template=@invoice.docx -F 'data=<invoice.json' -F steps=convert \
  http://localhost:9027/v1/render

import { openAsBlob } from 'node:fs';
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('template', await openAsBlob('invoice.docx'), 'invoice.docx');
form.append('data', await readFile('invoice.json', 'utf8'));
form.append('steps', 'convert');

const response = await fetch('http://localhost:9027/v1/render', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KEY,
    'X-Rusticdoc-Webhook-Url': 'https://receiver.example.com/documents',
  },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

import os
from pathlib import Path

import requests

response = requests.post(
    "http://localhost:9027/v1/render",
    headers={
        "X-Api-Key": os.environ["KEY"],
        "X-Rusticdoc-Webhook-Url": "https://receiver.example.com/documents",
    },
    files=[("template", open("invoice.docx", "rb"))],
    data={"data": Path("invoice.json").read_text(), "steps": "convert"},
)
response.raise_for_status()
print(response.json())

package main

import (
  "bytes"
  "io"
  "log"
  "mime/multipart"
  "net/http"
  "os"
  "path/filepath"
)

func main() {
  var body bytes.Buffer
  form := multipart.NewWriter(&body)
  attach(form, "template", "invoice.docx")
  data, err := os.ReadFile("invoice.json")
  if err != nil {
    log.Fatal(err)
  }
  form.WriteField("data", string(data))
  form.WriteField("steps", "convert")
  form.Close()

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/render", &body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("X-Rusticdoc-Webhook-Url", "https://receiver.example.com/documents")
  request.Header.Set("Content-Type", form.FormDataContentType())

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }
  if _, err := io.Copy(os.Stdout, response.Body); err != nil {
    log.Fatal(err)
  }
}

// attach adds the file at path to the form as the named field.
func attach(form *multipart.Writer, field, path string) {
  file, err := os.Open(path)
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()
  part, err := form.CreateFormFile(field, filepath.Base(path))
  if err != nil {
    log.Fatal(err)
  }
  if _, err := io.Copy(part, file); err != nil {
    log.Fatal(err)
  }
}

Fills a template and runs the steps.

Send a multipart form, or JSON with a templateId (see RenderJson).

Add Prefer: respond-async to get 202 at once, with the job in the body and its address in Location, and fetch the result from /v1/jobs/{id}/result once it is done. This needs RUSTICDOC_STORE.

Add X-Rusticdoc-Webhook-Url to get 204 at once and the result by webhook. With RUSTICDOC_WEBHOOK_SECRET set, each caller’s deliveries are signed with its own key: X-Rusticdoc-Signature is v1= and the hex HMAC-SHA256 of <timestamp>.<event>.<request id>.<body>, with the timestamp in X-Rusticdoc-Timestamp, the event in X-Rusticdoc-Event and the request id in X-Request-Id. The key is HMAC-SHA256(secret, principal), or the secret itself when the service requires no credentials; rusticdoc webhook-secret prints it.

Authorizations

api_key
bearer
basic

Parameters

Header Parameters

X-Rusticdoc-Webhook-Url

string | null

Deliver the result here instead of in the response

X-Rusticdoc-Webhook-Error-Url

string | null

Deliver failures here as JSON

Prefer

string | null

respond-async to run in the background and answer 202

Request Body^required

The multipart form /v1/render, /v1/render/batch and /v1/templates/validate accept.

object

assets

Images (PNG, JPEG, GIF, SVG), stylesheets and fonts an HTML page names by file name, as in <img src="logo.png">. Every stylesheet applies to the whole page. Nothing is fetched from anywhere else.

Array<string>

batchName

For /v1/render/batch: each file’s name, as a template.

string | null

bookmarks

For bookmarks: a JSON array of {"title", "page", "children"} that replaces the outline, sent as text.

Array<object> | null

object

certify

For sign: certify with DocMDP permission 1, 2 or 3 instead of approving.

integer | null format: int32

contactInfo

For sign: how to reach the signer.

string | null

ctx

JSON object visible as ctx, sent as text or as a file.

string | null

currency

The currency currency uses when given none, such as EUR. Wins over the template’s.

string | null

data

JSON object the template sees as its root, sent as text or as a file.

string | null

Example

{"customer": {"name": "Ada"}}

downloadFrom

Files to fetch from URLs instead of uploading them, as a JSON array of {"url": "..."} sent as text. At most 10 entries.

Array<object> | null

object

embeds

For embed: the files to attach.

Array<string>

embedsMetadata

For embed: a JSON object mapping a file name to {"mimeType": "..."}, sent as text.

object | null

facturxConformanceLevel

For factur-x: MINIMUM, BASIC_WL, BASIC, EN16931 (default) or EXTENDED.

string | null

facturxXml

For factur-x: the invoice XML to embed.

string format: binary

files

Further files, used by merge.

Array<string>

flatten

With a PDF template and data, true fixes the filled values into the page.

boolean | null

fonts

Fonts for this request only.

Array<string>

htmlEngine

What turns HTML into PDF: fulgur (default), a layout engine with no browser and no network, or libreoffice.

string | null

Example

fulgur

keep

What an Office template’s result may keep of what rendering takes out, comma-separated: macros, objects (OLE objects and ActiveX controls), externalLinks, privateLinks (hyperlinks to private addresses), or all. Default: none of them.

string | null

Example

privateLinks

lang

The language, such as fr, fr-CA or en-us, in any case. It wins over the template’s lang: it picks translations for t, and when CLDR has data for it, how number, currency and date write numbers, money and month names.

string | null

Example

fr-CA

level

For sign: b-b, b-t, b-lt or b-lta, as on /v1/pdf/sign.

string | null

location

For sign: where it was signed.

string | null

metadata

JSON object of metadata fields for metadata, sent as text.

string | null

outputFilename

File name of the result, without extension.

string | null

ownerPassword

For encrypt: the password that lifts its restrictions. Defaults to userPassword.

string | null

page

For a visible sign: the 1-based page. Default 1.

integer | null format: int32

pdfa

PDF/A level for pdfa: PDF/A-1b, PDF/A-2b, PDF/A-3b.

string | null

reason

For sign: why the document was signed.

string | null

rotateAngle

For rotate: 90 (default), 180, 270 or -90.

string | null

rotatePages

For rotate: the pages to turn, such as 1-3. Default all.

string | null

signatureImage

For sign: a PNG or JPEG to show the signature with, at page, x, y and width. With x and y and no image, the signature is shown as text: the signer, the date and the reason.

string format: binary

signerName

For sign: the signer’s name as shown.

string | null

signingKey

For sign: a named key instead of the default one.

string | null

splitBy

For /v1/render/batch: the array to render once per element.

string | null

splitMode

For split: pages (default) or intervals.

string | null

splitSpan

For split: page ranges such as 1-3,5 with pages, or a page count with intervals. Required by the step.

string | null

splitUnify

For split with pages: true gives one document holding the pages instead of one per range.

boolean | null

stamp

For stamp with an image or pdf source: the files to draw. At most five marks a request.

Array<string>

stampExpression

For stamp with a text source: the text to draw.

string | null

stampOptions

For stamp: a JSON object of pos, op, rot, sc, fontsize and fillc, each value a string, sent as text.

object | null

stampPages

For stamp: the pages to mark, such as 1-3. Default all.

string | null

stampSource

For stamp: what to draw over the page content, text, image or pdf.

string | null

steps

Comma-separated steps, run in the order given: convert, pdfa, pdfua, merge, split, watermark, stamp, underlay, rotate, flatten, optimize, bookmarks, metadata, embed, factur-x, encrypt, sign. Each reads the fields described as its own. sign signs cryptographically with the service’s key; it must be last and cannot be combined with encrypt.

string | null

Example

convert,pdfa,encrypt

stripAnnotations

With a PDF template and data, false keeps the annotations that held tags. They are removed by default.

boolean | null

template

The template file. Send this or templateId.

string format: binary

templateHash

The hex SHA-256 of a template this caller sent recently, in place of the file.

string | null

templateId

The id of a stored template, from POST /v1/templates, or an alias as name or name@version. Send this or template. Files in the form are then only further inputs, for merge.

string | null

timezone

The time zone date shows moments in: an offset such as +02:00, or an IANA zone such as Europe/Paris. Wins over the template’s.

string | null

Example

Europe/Paris

Output format for convert. Default pdf.

string | null

translations

Translations for t, by language, each a flat object of keys and texts. They win over the service’s dictionaries and the template’s own. At most 10,000 entries, keys of 256 bytes and texts of 16 KiB.

object | null

undefinedAsEmpty

true prints a value missing from the data as nothing instead of failing the render. Default false, so a misspelt name is an error.

boolean | null

underlay

For underlay: the PDF the document is laid over, page by page, such as letterhead or a pre-printed form.

string format: binary

userPassword

For encrypt: the password that opens the document.

string | null

watermark

For watermark with an image or pdf source: the files to draw. At most five marks a request.

Array<string>

watermarkExpression

For watermark with a text source: the text to draw.

string | null

watermarkOptions

For watermark: a JSON object of pos, op, rot, sc, fontsize and fillc, each value a string, sent as text.

object | null

watermarkPages

For watermark: the pages to mark, such as 1-3. Default all.

string | null

watermarkSource

For watermark: what to draw under the page content, text, image or pdf.

string | null

width

For a visible sign: width in points. Default the image’s natural size, or 200 for text.

number | null format: float

For a visible sign: points from the page’s left edge.

number | null format: float

For a visible sign: points from the page’s bottom edge.

number | null format: float

The JSON body /v1/render, /v1/render/batch and /v1/templates/validate accept with Content-Type: application/json, for a stored template: there are no files to send. Every text field of the multipart form is accepted under the same name, with the same meaning and limits; objects such as data and metadata are sent as JSON rather than as text, and steps may be a list. Fields that carry files cannot be sent.

object

batchName

For /v1/render/batch: each file’s name, as a template.

string | null

ctx

The object visible as ctx.

currency

The currency currency uses when given none, such as EUR. Wins over the template’s.

string | null

data

The object the template sees as its root.

downloadFrom

URLs to fetch as further inputs, as on the multipart form.

Array<object> | null

object

htmlEngine

fulgur (default) or libreoffice, for HTML.

string | null

keep

string | null

Example

privateLinks

lang

string | null

Example

fr-CA

metadata

Metadata fields for metadata.

outputFilename

File name of the result, without extension.

string | null

ownerPassword

string | null

pdfa

PDF/A level for pdfa.

string | null

splitBy

For /v1/render/batch: the array to render once per element.

string | null

steps

The steps in order, as a list or as comma-separated text.

Array<string> | null

Example

[
  "convert",
  "pdfa"
]

templateId

required

The stored template: its id, or an alias as name or name@version.

string

Example

invoice

timezone

The time zone date shows moments in: an offset such as +02:00, or an IANA zone such as Europe/Paris. Wins over the template’s.

string | null

Example

Europe/Paris

Output format for convert. Default pdf.

string | null

translations

object | null

undefinedAsEmpty

true prints a value missing from the data as nothing.

boolean | null

userPassword

string | null

Responses

200

The rendered file

application/octet-stream

The file, as bytes.

string format: binary

202

Accepted as a background job (Prefer: respond-async)

application/json

A background job.

object

createdAt

required

RFC 3339, to the millisecond.

string

error

Present once it failed: what the request would have answered, as error, message and status.

object | null

expiresAt

When the job and its result are removed.

string | null

finishedAt

string | null

required

string

requestId

required

The X-Request-Id of the request that started it.

string

result

One of:

object
null

Present once it is done; download it from /v1/jobs/{id}/result.

object

contentType

required

string

name

required

string

sha256

required

Hex SHA-256 of the content.

string

size

required

integer format: int64

runsUntil

required

A job that has not ended by then is reported as failed with job_lost: the container running it stopped.

string

startedAt

string | null

status

required

queued, running, done or failed.

string

Example

{
  "id": "01966f3e-7c1a-7d3c-9a44-1d2f5a6b7c8d",
  "result": {
    "contentType": "application/pdf",
    "name": "invoice.pdf"
  },
  "status": "done"
}

204

Accepted; the result goes to the webhook

400

The request is wrong

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

401

Credentials required

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

422

The template failed to render

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

501

Not supported in this version

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

503

An engine is unavailable or the request timed out

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

Render a template

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

202

Example

204

400

Example

401

Example

422

Example

501

Example

503

Example

Request Body^required