# API Snippets : gérer vos snippets


Référence complète de l’API pour lister, récupérer, créer, modifier et supprimer des snippets dans PDFMonkey.

> [!TIP]
> **Vous découvrez les snippets ?**
>
> Les snippets permettent de partager du code entre plusieurs modèles. Consultez [Réutiliser du code](../modeles-code/reutiliser-du-code.md) pour savoir comment les charger et les inclure dans un modèle. L’API Snippets est utile lorsque vous gérez vos snippets par programmation, par exemple pour les synchroniser depuis un dépôt Git. Pour les modifier au quotidien, la [CLI](../integrations/cli.md) est souvent l’option la plus simple.


## Authentification {#authentication}

Toutes les requêtes nécessitent un token Bearer dans l’en-tête `Authorization` :

```
Authorization: Bearer YOUR_SECRET_KEY
```

Consultez [Authentification](./authentication.md) pour savoir comment trouver votre clé API.

## L’objet Snippet {#the-snippet-object}

Un Snippet est un bloc de code HTML + Liquid nommé, qui appartient à un espace de travail. Les modèles le désignent par son `identifier` :

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

### Attributs {#attributes}

```json5 title="Objet 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,
}
```

| Attribut            | Type                        | Description                                                                                                 |
| :------------------ | :-------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `id`                | UUID                        | Identifiant unique.                                                                                         |
| `workspace_id`      | UUID                        | Identifiant unique de l’[espace de travail](../premiers-pas/_index.md) du snippet.                          |
| `identifier`        | String                      | Nom utilisé pour charger le snippet dans les modèles (1 à 100 caractères). Unique dans l’espace de travail. |
| `code`              | String                      | Code HTML + Liquid du snippet. Doit être du Liquid valide.                                                  |
| `snippet_folder_id` | UUID ou `null`              | ID du [dossier de snippets](#snippet-folders) qui contient le snippet.                                      |
| `creator_id`        | UUID                        | ID de l’utilisateur qui a créé le snippet.                                                                  |
| `creator_name`      | String                      | Nom affiché de l’utilisateur qui a créé le snippet.                                                         |
| `updater_id`        | UUID                        | ID du dernier utilisateur à avoir modifié le snippet. Déterminé par la clé API utilisée pour la requête.    |
| `updater_name`      | String                      | Nom affiché du dernier utilisateur à avoir modifié le snippet.                                              |
| `created_at`        | String (ISO 8601)           | Date de création du snippet.                                                                                |
| `updated_at`        | String (ISO 8601)           | Date de dernière modification du snippet.                                                                   |
| `deleted_at`        | String (ISO 8601) ou `null` | Toujours `null` pour les snippets renvoyés par l’API.                                                       |

## Lister les snippets {#list-snippets}

**`GET /api/v1/snippets`**

Renvoie une liste paginée des snippets d’un espace de travail, code compris.

### Paramètres de requête {#query-parameters}

| Nom               | Type          | Requis  | Description                                                                                                                                    |
| :---------------- | :------------ | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `q[workspace_id]` | String (UUID) | **Oui** | L’espace de travail dont lister les snippets. Accepte aussi `q[workspaceId]`, `q[app_id]` ou `q[appId]`. Sans ce paramètre, la liste est vide. |
| `q[folders]`      | String        | Non     | Liste d’ID de dossiers séparés par des virgules. Utilisez `"none"` pour les snippets hors dossier, ou `"all"` (par défaut) pour tous.          |
| `q[search]`       | String        | Non     | Ne renvoie que les snippets dont l’`identifier` contient ce texte (sans tenir compte de la casse).                                             |
| `page`            | Integer       | Non     | Numéro de page (24 snippets par page). Utilisez `all` pour obtenir tous les snippets en une seule réponse, sans `meta`.                        |
| `sort`            | String        | Non     | Attribut de tri, par exemple `identifier`. Préfixez-le par `-` pour un tri décroissant, par exemple `-updated_at`.                             |

### Requête {#list-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']);
```



### Réponse {#list-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
  }
}
```

## Récupérer un snippet {#get-a-snippet}

**`GET /api/v1/snippets/{id}`**

Renvoie un [objet Snippet](#the-snippet-object).

### Requête {#get-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']);
```



### Réponse {#get-response}

Renvoie `200 OK` avec un objet `snippet` :

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

## Créer un snippet {#create-a-snippet}

**`POST /api/v1/snippets`**

Crée un nouveau snippet dans un espace de travail.

### Paramètres {#create-parameters}

Tous les paramètres sont imbriqués sous une clé `snippet`.

| Nom                 | Type          | Requis  | Description                                                                                                       |
| :------------------ | :------------ | :------ | :---------------------------------------------------------------------------------------------------------------- |
| `workspace_id`      | String (UUID) | **Oui** | L’espace de travail dans lequel créer le snippet.                                                                 |
| `identifier`        | String        | **Oui** | Nom utilisé pour charger le snippet (1 à 100 caractères). Unique dans l’espace de travail.                        |
| `code`              | String        | Non     | Code HTML + Liquid. Doit être du Liquid valide.                                                                   |
| `snippet_folder_id` | String (UUID) | Non     | [Dossier de snippets](#snippet-folders) dans lequel placer le snippet. Doit appartenir au même espace de travail. |

### Requête {#create-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']);
```



### Réponse {#create-response}

Renvoie `201 Created` avec l’objet `snippet` complet. L’en-tête `Location` contient l’URL du nouveau snippet.

### Erreurs de validation {#validation-errors}

Si un champ est manquant ou invalide, l’API renvoie `422 Unprocessable Entity`. Un code Liquid invalide est signalé sous la clé `code`, avec le message de l’analyseur Liquid.

```json title="422 Unprocessable Entity"
{
  "errors": {
    "identifier": ["has already been taken"]
  }
}
```

## Modifier un snippet {#update-a-snippet}

**`PUT /api/v1/snippets/{id}`**

Modifie un snippet existant. Seuls les champs présents dans le corps de la requête sont modifiés. `PATCH` est également accepté.

### Paramètres {#update-parameters}

Tous les paramètres sont imbriqués sous une clé `snippet`. Les champs acceptés sont les mêmes que pour [Créer un snippet](#create-a-snippet). Envoyez `"snippet_folder_id": null` pour sortir un snippet de son dossier.

> [!WARNING]
> **Renommer un snippet**
>
> Les modèles chargent les snippets par leur `identifier`. Si vous renommez un snippet, mettez à jour les tags `load_snippets` et `include` des modèles qui l’utilisent.


### Requête {#update-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']);
```



### Réponse {#update-response}

Renvoie `200 OK` avec l’objet `snippet` modifié.

## Supprimer un snippet {#delete-a-snippet}

**`DELETE /api/v1/snippets/{id}`**

Supprime un snippet. Il n’apparaît plus ni dans l’API ni dans le Dashboard.

### Requête {#delete-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);
```



### Réponse {#delete-response}

Renvoie `204 No Content` avec un corps vide.

## Dossiers de snippets {#snippet-folders}

Les dossiers de snippets regroupent les snippets d’un espace de travail, comme les dossiers de modèles regroupent les modèles. Un snippet ne peut se trouver que dans un seul dossier, défini par son `snippet_folder_id`.

### L’objet SnippetFolder {#the-snippetfolder-object}

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

| Attribut       | Type              | Description                                           |
| :------------- | :---------------- | :---------------------------------------------------- |
| `id`           | UUID              | Identifiant unique.                                   |
| `workspace_id` | UUID              | Identifiant unique de l’espace de travail du dossier. |
| `identifier`   | String            | Nom du dossier (1 à 100 caractères).                  |
| `created_at`   | String (ISO 8601) | Date de création du dossier.                          |
| `updated_at`   | String (ISO 8601) | Date de dernière modification du dossier.             |

### Endpoints {#endpoints}

| Méthode  | Chemin                         | Description                                                                                                          |
| :------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/snippet_folders`      | Liste les dossiers d’un espace de travail. Nécessite `q[workspace_id]`, comme [Lister les snippets](#list-snippets). |
| `GET`    | `/api/v1/snippet_folders/{id}` | Récupère un dossier.                                                                                                 |
| `POST`   | `/api/v1/snippet_folders`      | Crée un dossier. Envoyez `workspace_id` et `identifier` sous une clé `snippet_folder`.                               |
| `PUT`    | `/api/v1/snippet_folders/{id}` | Renomme un dossier. Envoyez `identifier` sous une clé `snippet_folder`.                                              |
| `DELETE` | `/api/v1/snippet_folders/{id}` | Supprime un dossier **et tous les snippets qu’il contient**. Renvoie `204 No Content`.                               |

Les réponses placent le dossier sous une clé `snippet_folder`, ou la liste des dossiers sous une clé `snippet_folders`.

```bash title="Créer un dossier"
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": "Factures"
    }
  }'
```

> [!CAUTION]
> **Supprimer un dossier supprime ses snippets**
>
> Pour conserver les snippets d’un dossier que vous allez supprimer, sortez-les d’abord du dossier en [modifiant](#update-a-snippet) chacun d’eux avec `"snippet_folder_id": null`.


## Pages associées {#related-pages}

- **[Réutiliser du code](../modeles-code/reutiliser-du-code.md)** — Chargez et incluez des snippets dans vos modèles.
- **[CLI](../integrations/cli.md)** — Modifiez vos snippets en local et synchronisez-les avec PDFMonkey.
- **[Authentification](./authentication.md)** — Trouvez votre clé API et authentifiez vos requêtes.
- **[API Templates](./templates.md)** — Créez, listez et gérez vos modèles.
- **[SDK Ruby](../integrations/sdk-ruby.md)** et **[SDK Node.js](../integrations/sdk-nodejs.md)** — Gérez vos snippets depuis votre code.


## FAQ

**Qu’est-ce qu’un Snippet dans PDFMonkey ?**

Un Snippet est un bloc de code HTML + Liquid nommé, stocké dans un espace de travail. Tous les modèles de cet espace de travail peuvent le charger avec le tag load_snippets et l’insérer avec le tag include.

**Comment lister les snippets avec l’API PDFMonkey ?**

Envoyez une requête GET à /api/v1/snippets avec un paramètre q[workspace_id]. Sans ce paramètre, l’API renvoie une liste vide. Vous pouvez affiner les résultats avec q[folders] et q[search].

**Deux snippets peuvent-ils avoir le même nom ?**

Pas dans le même espace de travail. Les modèles font référence à un snippet par son identifier, qui doit donc être unique dans son espace de travail. L’API renvoie une erreur 422 si l’identifier est déjà utilisé.
