Skip to content
PaprikaPaprikaPaprika

Render it from the API

In about 15 minutes you’ll render badges from the template published in Design your first template, each with its own name and role, by calling the generation API. Every request here is in the API reference too.

Before you start

Section titled “Before you start”

You need:

  • The API’s address and an API key with the render and publish scopes. Whoever runs Paprika for your organisation gives you both.
  • A terminal: the commands are for curl on macOS and Linux, and for PowerShell on Windows.

Keep the address and the key where the commands find them:

Terminal window
export PAPRIKA_URL=https://paprika.example.com
export PAPRIKA_KEY=ppk_…

Render a badge

Section titled “Render a badge”

  1. Find the template. Ask for the templates named badge.paprika:

    Terminal window
    curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates?filename=badge.paprika"

    The answer lists it, with its id and its latest version:

    [
      {
        "id": "tpl_9fK2mQ7rLx4VbN1s",
        "filename": "badge.paprika",
        "title": null,
        "policy": {},
        "createdAt": "2026-11-06T15:02:05.115Z",
        "latest": 1
      }
    ]

    Copy the id for the next steps. If the list is empty, nobody has published the badge yet: see No badge yet? below.

  2. Render it with your values. Send a value for each text field, and save the PDF the API answers with:

    Terminal window
    curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -H "Accept: application/pdf" -d '{"values": {"name": "Grace Hopper", "role": "Keynote speaker"}}' -o grace.pdf "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/render"

    latest renders the newest version; a number (versions/1) renders that one. The photo isn’t given, so the badge shows the photo field’s default.

  3. Open grace.pdf. The badge shows Grace Hopper, Keynote speaker and the default photo, laid out as in the editor.

  4. Make another. Change the values, say {"name": "Alan Turing", "role": "Panel chair"}, and save to alan.pdf. Each request makes a badge of its own from the same published version.

When a value is wrong

Section titled “When a value is wrong”

The template’s fields are its contract. Leave out the name and send {"values": {"role": "Speaker"}}: instead of a PDF, the API answers 422 with every problem and the field it concerns:

{
  "code": "values-invalid",
  "message": "The values have 1 problem; see errors",
  "errors": [{ "field": "name", "code": "field-missing", "message": "Missing required field: name" }],
  "requestId": "4de94be7"
}

With curl, leave out -o grace.pdf to see the answer. The request id is in the server’s log too, to find the request there.

No badge yet?

Section titled “No badge yet?”

If nobody has published the badge, download badge.paprika and publish it yourself: make the template, then send the file as its first version.

Terminal window
curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"filename": "badge.paprika"}' "$PAPRIKA_URL/v1/templates"
curl -H "Authorization: Bearer $PAPRIKA_KEY" --data-binary @badge.paprika "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions"

The first answers with the new template’s id; use it in the second, in place of tpl_9fK2mQ7rLx4VbN1s. The second answers with the version, "version": 1.

What’s next

Section titled “What’s next”