Templates and versions

A template is a name (badge.paprika) and an id (tpl_…). Each time a package is published to it, it gets a new version, numbered 1, 2, 3…; a version never changes once published. Requests render a version by its number, or latest. Designers usually publish from the editor; you can publish packages yourself too.

Publish a package

Make the template once, by its file name:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"filename": "badge.paprika"}' "$PAPRIKA_URL/v1/templates"

{ "id": "tpl_9fK2mQ7rLx4VbN1s", "filename": "badge.paprika", "title": null, "policy": {} }

Then send the package (a .paprika file saved from the editor) as its next version:

curl -H "Authorization: Bearer $PAPRIKA_KEY" --data-binary @badge.paprika "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions"

{
  "template": "tpl_9fK2mQ7rLx4VbN1s",
  "version": 1,
  "fields": { "name": { "type": "text", "required": true } },
  "warnings": []
}

The server checks the package before it becomes a version: its files, the rights of its fonts, and a layout with its sample values. A layout error refuses it with 422 template-invalid, listing the errors; warnings are kept with the version. Sending the same contents again answers 200 with the version they already are, so publishing is safe to retry.

A package may leave out fonts that are in your organisation’s font library (large fonts, and fonts that may not be redistributed): the version then uses the library’s, and the library keeps them while a version does.

Find templates and versions

List the templates, or find one by its file name:

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

A template with its versions, newest first:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s"

A version’s fields, sample values and warnings, by number or latest:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest"

Its first page as a picture (a PNG within 400 × 400 pixels), for showing in your own system:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -o thumbnail.png "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/thumbnail"

And its package, to open in the editor or keep:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -o badge-v1.paprika "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/1/package"

What values a version takes

A version’s fields are its contract with your requests. Ask for it as a JSON Schema, to check values in your own system or generate forms, or let the server check values without rendering:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/schema"
curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Grace Hopper", "role": "Keynote speaker"}' "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/validate"

The values reference says what each kind of value may be.

Rename or delete

Rename a template with PATCH. Deleting a version, or a template with all its versions, can’t be undone, and requests naming them fail from then on:

curl -X DELETE -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/1"