# PDFs

## Create a PDF asynchronously

<mark style="color:green;">`POST`</mark> `https://api.usestencil.com/v1/pdfs`

#### Request Body

| Name                                       | Type   | Description                                               |
| ------------------------------------------ | ------ | --------------------------------------------------------- |
| modfications                               | array  | Array of modification objects                             |
| metadata                                   | object | Extra metadata to be included together with the webhook   |
| webhook\_url                               | string | URL of the webhook to be called when the pdf is generated |
| template<mark style="color:red;">\*</mark> | string | The ID of the template                                    |

{% tabs %}
{% tab title="202: Accepted PDF is accepted for processing" %}

```json
{
  "created_at": "2023-04-06T12:04:58.877Z",
  "id": "e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "log": null,
  "metadata": {},
  "modifications": [
    {
      "name": "image_2",
      "src": "https://usestencil.s3.amazonaws.com/dev/uploads/814bb298-a5c9-4df8-b367-cb81be9e8839/efaa4261-94d7-4ceb-b2ec-cf60990afb07/photo-1613569973485-c6ecb241be47-311746964.png"
    },
    {
      "name": "text_3",
      "text": "YELLOW WOOL HOODIEZZ"
    },
    {
      "name": "text_5",
      "text": "USD 49.99"
    }
  ],
  "pdf_url": null,
  "self": "http://api.usestencil.test:4000/v1/pdfs/e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "status": "pending",
  "template_id": "6132c433-aa49-4774-8eed-c402898f1437",
  "webhook_response_body": null,
  "webhook_response_code": null,
  "webhook_url": null
}
```

You can send a `GET` request to `self` to check the status of PDF generation. See the next API for details.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
PDF generation uses 2 credits instead of 1.
{% endhint %}

## Get the PDF

<mark style="color:blue;">`GET`</mark> `https://api.usestencil.com/v1/pdfs/:pdf_id`

#### Path Parameters

| Name                                      | Type   | Description                                                                                 |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------- |
| pdf\_id<mark style="color:red;">\*</mark> | string | <p>The PDF id. </p><p></p><p>You can get the PDF id from the response of creating a PDF</p> |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "created_at": "2023-04-06T12:04:58.877Z",
  "id": "e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "log": null,
  "metadata": {},
  "modifications": [
    {
      "name": "image_2",
      "src": "https://usestencil.s3.amazonaws.com/dev/uploads/814bb298-a5c9-4df8-b367-cb81be9e8839/efaa4261-94d7-4ceb-b2ec-cf60990afb07/photo-1613569973485-c6ecb241be47-311746964.png"
    },
    {
      "name": "text_3",
      "text": "YELLOW WOOL HOODIEZZ"
    },
    {
      "name": "text_5",
      "text": "USD 49.99"
    }
  ],
  "pdf_url": "https://usestencil.s3.amazonaws.com/dev/pdfs/6132c433-aa49-4774-8eed-c402898f1437/e45e9dc7-8eee-476c-9031-0d1040881d1a.pdf",
  "self": "http://api.usestencil.test:4000/v1/pdfs/e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "status": "completed",
  "template_id": "6132c433-aa49-4774-8eed-c402898f1437",
  "webhook_response_body": null,
  "webhook_response_code": null,
  "webhook_url": null
}
       
```

{% endtab %}
{% endtabs %}

For PDF generation, we only support asynchronous request, as PDF generation usually takes a slightly longer time than image generation.

## Search generated PDFs

<mark style="color:green;">`POST`</mark> `/v1/pdfs/search?q=<query>`

Search for generated PDFs based on your modification inputs. It searches for given query in your modification inputs.  Query is case insensitive.

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "meta": {
    "next": null,
    "total_count": 1,
    "previous": null
  },
  "results": [
    {
      "id": "fa032cc8-fa07-4221-8411-4279b46683d5",
      "status": "completed",
      "self": "http://api.usestencil.com/v1/pdfs/fa032cc8-fa07-4221-8411-4279b46683d5",
      "log": "{}",
      "metadata": {},
      "created_at": "2025-09-23T11:56:21.562Z",
      "template_id": "8be62eca-72de-4f81-9edc-a4dbeee6986f",
      "webhook_url": null,
      "modifications": [
        {
          "name": "rect_4"
        },
        {
          "name": "image",
          "src": "https://images.unsplash.com/photo-1503327431567-3ab5e6e79140?q=80&w=3328&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
        },
        {
          "name": "product",
          "text": "JEANS"
        },
        {
          "name": "price",
          "text": "$49.99"
        },
        {
          "name": "qrcode_5",
          "value": "https://usestencil.com"
        }
      ],
      "webhook_response_code": null,
      "webhook_response_body": null,
      "pdf_url": "https://usestencil.s3.amazonaws.com/dev/pdfs/8be62eca-72de-4f81-9edc-a4dbeee6986f/fa032cc8-fa07-4221-8411-4279b46683d5.pdf"
    }
  ]
}

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usestencil.com/api/endpoints/pdfs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.