# Snippets API: Manage Reusable Liquid Snippets


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

> [!TIP]
> **New to snippets?**
>
> Snippets let you share code between templates. See [Reusing Code](../code-templates/reusing-code.md) 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](../integrations/cli.md) is often the easiest option.


## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_SECRET_KEY
```

See [Authentication](./authentication.md) 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`:

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

### Attributes

```json5 title="Snippet object"
{
  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](../getting-started/_index.md).                |
| `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](#snippet-folders) 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**

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

**Node.js**

```javascript
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);
```

**Python**

```python
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**

```php
<?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

```json title="200 OK"
{
  "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](#the-snippet-object).

### Request








**curl**

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

**Ruby**

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

puts snippet.identifier
puts snippet.code
```

**Node.js**

```javascript
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);
```

**Python**

```python
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**

```php
<?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:

```json title="200 OK"
{
  "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](#snippet-folders) to place the snippet in. Must belong to the same workspace. |

### Request








**curl**

```bash
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>"
    }
  }'
```

**Ruby**

```ruby
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
```

**Node.js**

```javascript
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);
```

**Python**

```python
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**

```php
<?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.

```json title="422 Unprocessable Entity"
{
  "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](#create-a-snippet) are accepted. Send `"snippet_folder_id": null` to take a snippet out of its folder.

> [!WARNING]
> **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**

```bash
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>"
    }
  }'
```

**Ruby**

```ruby
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>',
)
```

**Node.js**

```javascript
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);
```

**Python**

```python
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**

```php
<?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**

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

**Ruby**

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

**Node.js**

```javascript
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
```

**Python**

```python
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**

```php
<?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

```json title="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](#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.

```bash title="Create a folder"
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"
    }
  }'
```

> [!CAUTION]
> **Deleting a folder deletes its snippets**
>
> To keep the snippets of a folder you are about to delete, first move them out by [updating](#update-a-snippet) each one with `"snippet_folder_id": null`.


## Related pages

- **[Reusing Code](../code-templates/reusing-code.md)** -- Load and include snippets in your templates.
- **[CLI](../integrations/cli.md)** -- Edit snippets locally and sync them to PDFMonkey.
- **[Authentication](./authentication.md)** -- Find your API key and authenticate requests.
- **[Templates API](./templates.md)** -- Create, list, and manage templates.
- **[Ruby SDK](../integrations/ruby-sdk.md)** and **[Node.js SDK](../integrations/node-sdk.md)** -- Manage snippets from your code.


## FAQ

**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.