What is a Snippet in PDFMonkey?

A Snippet is a named block of HTML + Liquid code stored in a workspace. Any template of that workspace can load it with the load_snippets tag and insert it with the include tag.

How do I list snippets with the PDFMonkey API?

Send a GET request to /api/v1/snippets with a q[workspace_id] parameter. Without it, the API returns an empty list. You can narrow the results with q[folders] and q[search].

Can two snippets have the same name?

Not in the same workspace. The identifier is how templates refer to a snippet, so it must be unique within its workspace. The API returns a 422 error if the identifier is already taken.

Snippets API: List, Retrieve, Create, Update, and Delete Snippets

Complete API reference for listing, retrieving, creating, updating, and deleting snippets in PDFMonkey.

New to snippets?

Snippets let you share code between templates. See Reusing Code to learn how to load and include them in a template. The Snippets API is useful when you manage snippets programmatically, for example to sync them from a Git repository. For day-to-day editing, the CLI is often the easiest option.

Authentication #

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_SECRET_KEY

See Authentication for how to find your API key.

The Snippet object #

A Snippet is a named block of HTML + Liquid code that belongs to a workspace. Templates refer to it by its identifier:

{%- load_snippets 'invoice-header' -%}
{% include 'invoice-header', company: company %}

Attributes #

{
  id: "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  workspace_id: "3161c5e5-9966-4630-9b07-63f718092784",
  identifier: "invoice-header",
  code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
  snippet_folder_id: null,
  creator_id: "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
  creator_name: "Jane Doe",
  updater_id: "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
  updater_name: "Jane Doe",
  created_at: "2050-01-02T03:04:05.678+02:00",
  updated_at: "2050-01-02T03:04:05.678+02:00",
  deleted_at: null,
}

Attribute	Type	Description
`id`	UUID	Unique identifier.
`workspace_id`	UUID	Unique identifier of the snippet’s workspace.
`identifier`	String	Name used to load the snippet in templates (1–100 characters). Unique within the workspace.
`code`	String	HTML + Liquid code of the snippet. Must be valid Liquid.
`snippet_folder_id`	UUID or `null`	ID of the snippet folder the snippet is in.
`creator_id`	UUID	ID of the user who created the snippet.
`creator_name`	String	Display name of the user who created the snippet.
`updater_id`	UUID	ID of the user who last updated the snippet. Set from the API key used for the request.
`updater_name`	String	Display name of the user who last updated the snippet.
`created_at`	String (ISO 8601)	Timestamp when the snippet was created.
`updated_at`	String (ISO 8601)	Timestamp when the snippet was last updated.
`deleted_at`	String (ISO 8601) or `null`	Always `null` for snippets returned by the API.

List snippets #

GET /api/v1/snippets

Returns a paginated list of the snippets in a workspace, including their code.

Query parameters #

Name	Type	Required	Description
`q[workspace_id]`	String (UUID)	Yes	The workspace to list snippets from. Also accepts `q[workspaceId]`, `q[app_id]`, or `q[appId]`. Without it, the list is empty.
`q[folders]`	String	No	Comma-separated list of folder IDs. Use `"none"` for snippets not in any folder, or `"all"` (default) for all snippets.
`q[search]`	String	No	Only return snippets whose `identifier` contains this text (case-insensitive).
`page`	Integer	No	Page number for pagination (24 snippets per page). Use `all` to get every snippet in one response, without `meta`.
`sort`	String	No	Attribute to sort by, for example `identifier`. Prefix with `-` for descending order, for example `-updated_at`.

Request #

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  'https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784'

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784", {
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

const data = await response.json();
console.log(data.snippets);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/snippets',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    params={
        'q[workspace_id]': '3161c5e5-9966-4630-9b07-63f718092784',
    },
)

data = response.json()
print(data['snippets'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippets']);

Response #

{
  "snippets": [
    {
      "id": "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "invoice-header",
      "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>",
      "snippet_folder_id": null,
      "creator_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
      "creator_name": "Jane Doe",
      "updater_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
      "updater_name": "Jane Doe",
      "created_at": "2050-01-02T03:04:05.678+02:00",
      "updated_at": "2050-01-02T03:04:05.678+02:00",
      "deleted_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

Get a snippet #

GET /api/v1/snippets/{id}

Returns a single Snippet object.

Request #

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b

snippet = Pdfmonkey::Snippet.fetch('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

puts snippet.identifier
puts snippet.code

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Response #

Returns 200 OK with a snippet object:

{
  "snippet": {
    "id": "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
    "identifier": "invoice-header",
    "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>",
    "snippet_folder_id": null,
    "creator_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
    "creator_name": "Jane Doe",
    "updater_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
    "updater_name": "Jane Doe",
    "created_at": "2050-01-02T03:04:05.678+02:00",
    "updated_at": "2050-01-02T03:04:05.678+02:00",
    "deleted_at": null
  }
}

Create a snippet #

POST /api/v1/snippets

Creates a new snippet in a workspace.

Parameters #

All parameters are nested under a snippet key.

Name	Type	Required	Description
`workspace_id`	String (UUID)	Yes	The workspace to create the snippet in.
`identifier`	String	Yes	Name used to load the snippet (1–100 characters). Unique within the workspace.
`code`	String	No	HTML + Liquid code. Must be valid Liquid.
`snippet_folder_id`	String (UUID)	No	Snippet folder to place the snippet in. Must belong to the same workspace.

Request #

curl https://api.pdfmonkey.io/api/v1/snippets \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet": {
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "invoice-header",
      "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>"
    }
  }'

snippet = Pdfmonkey::Snippet.create(
  workspace_id: '3161c5e5-9966-4630-9b07-63f718092784',
  identifier: 'invoice-header',
  code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
)

puts snippet.id

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    snippet: {
      workspace_id: "3161c5e5-9966-4630-9b07-63f718092784",
      identifier: "invoice-header",
      code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
    },
  }),
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/snippets',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'snippet': {
            'workspace_id': '3161c5e5-9966-4630-9b07-63f718092784',
            'identifier': 'invoice-header',
            'code': '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
        },
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'snippet' => [
            'workspace_id' => '3161c5e5-9966-4630-9b07-63f718092784',
            'identifier' => 'invoice-header',
            'code' => '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Response #

Returns 201 Created with the full snippet object. The Location header contains the URL of the new snippet.

Validation errors #

If a field is missing or invalid, the API returns 422 Unprocessable Entity. Invalid Liquid in code is reported under the code key with the Liquid parser’s message.

{
  "errors": {
    "identifier": ["has already been taken"]
  }
}

Update a snippet #

PUT /api/v1/snippets/{id}

Updates an existing snippet. Only the fields you include in the request body are changed. PATCH is also accepted.

Parameters #

All parameters are nested under a snippet key. The same fields as Create a snippet are accepted. Send "snippet_folder_id": null to take a snippet out of its folder.

Renaming a snippet

Templates load snippets by identifier. If you rename a snippet, update the load_snippets and include tags of the templates that use it.

Request #

curl https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet": {
      "code": "<header class=\"invoice-header\"><img src=\"{{ company.logo_url }}\"><h1>{{ company.name }}</h1></header>"
    }
  }'

snippet = Pdfmonkey::Snippet.fetch('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

snippet.update!(
  code: '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
)

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  method: "PUT",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    snippet: {
      code: '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
    },
  }),
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.put(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'snippet': {
            'code': '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
        },
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'snippet' => [
            'code' => '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Response #

Returns 200 OK with the updated snippet object.

Delete a snippet #

DELETE /api/v1/snippets/{id}

Deletes a snippet. It no longer appears in the API or the Dashboard.

Request #

curl https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Pdfmonkey::Snippet.delete('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

console.log(response.status); // => 204

import requests

response = requests.delete(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

print(response.status_code)  # => 204

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // => 204
curl_close($ch);

Response #

Returns 204 No Content with an empty body.

Snippet folders #

Snippet folders group the snippets of a workspace, the same way template folders group templates. A snippet is in at most one folder, set by its snippet_folder_id.

The SnippetFolder object #

{
  "id": "7e3a9c1d-2b4f-4a6e-8c0d-1f2e3a4b5c6d",
  "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
  "identifier": "Invoices",
  "created_at": "2050-01-02T03:04:05.678+02:00",
  "updated_at": "2050-01-02T03:04:05.678+02:00"
}

Attribute	Type	Description
`id`	UUID	Unique identifier.
`workspace_id`	UUID	Unique identifier of the folder’s workspace.
`identifier`	String	Name of the folder (1–100 characters).
`created_at`	String (ISO 8601)	Timestamp when the folder was created.
`updated_at`	String (ISO 8601)	Timestamp when the folder was last updated.

Endpoints #

Method	Path	Description
`GET`	`/api/v1/snippet_folders`	List the folders of a workspace. Requires `q[workspace_id]`, like List snippets.
`GET`	`/api/v1/snippet_folders/{id}`	Get a folder.
`POST`	`/api/v1/snippet_folders`	Create a folder. Send `workspace_id` and `identifier` under a `snippet_folder` key.
`PUT`	`/api/v1/snippet_folders/{id}`	Rename a folder. Send `identifier` under a `snippet_folder` key.
`DELETE`	`/api/v1/snippet_folders/{id}`	Delete a folder and every snippet in it. Returns `204 No Content`.

Responses wrap the folder in a snippet_folder key, or a list of folders in a snippet_folders key.

curl https://api.pdfmonkey.io/api/v1/snippet_folders \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet_folder": {
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "Invoices"
    }
  }'

Deleting a folder deletes its snippets

To keep the snippets of a folder you are about to delete, first move them out by updating each one with "snippet_folder_id": null.

Reusing Code – Load and include snippets in your templates.
CLI – Edit snippets locally and sync them to PDFMonkey.
Authentication – Find your API key and authenticate requests.
Templates API – Create, list, and manage templates.
Ruby SDK and Node.js SDK – Manage snippets from your code.

Frequently asked questions

What is a Snippet in PDFMonkey?: A Snippet is a named block of HTML + Liquid code stored in a workspace. Any template of that workspace can load it with the load_snippets tag and insert it with the include tag.
How do I list snippets with the PDFMonkey API?: Send a GET request to /api/v1/snippets with a q[workspace_id] parameter. Without it, the API returns an empty list. You can narrow the results with q[folders] and q[search].
Can two snippets have the same name?: Not in the same workspace. The identifier is how templates refer to a snippet, so it must be unique within its workspace. The API returns a 422 error if the identifier is already taken.

Snippets API: List, Retrieve, Create, Update, and Delete Snippets

Authentication #

The Snippet object #

Attributes #

List snippets #

Query parameters #

Request #

Response #

Get a snippet #

Request #

Response #

Create a snippet #

Parameters #

Request #

Response #

Validation errors #

Update a snippet #

Parameters #

Request #

Response #

Delete a snippet #

Request #

Response #

Snippet folders #

The SnippetFolder object #

Endpoints #

Related pages #

Frequently asked questions