# Collections

## Use cases

Generally, there are two use cases of collection,

1. **To create images from multiple similar templates in a collection.**

   Image if you have a similar template but with different dimension. For example, you could have three templates - one for Instagram post, one for Pinterest, and one for open graph.
2. **To create image from randomly selected template in a collection.**

   If you have multiple templates with similar content but with different design, you might want to generate an image randomly from the collection of templates. This is useful if you want to create Instagram post but you don't want the design to be the same.

## How to create template collection

Before you can send a request to collection endpoint, you need to create the collection first.

1. Go to "Collections" tab and click on "+ New Collection"

![](https://1726200576-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYeUDPAhozAcUAcc2Lr%2F-Miv0SHl5K7ewLIXsfqn%2F-Miv0eePIqybL5BAI9Y-%2Fimage.png?alt=media\&token=efe55399-c447-40f1-92ec-b958073dd85e)

2\. Add the template that you want to add into the collection and save your changes.

![](https://1726200576-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYeUDPAhozAcUAcc2Lr%2F-Miv0SHl5K7ewLIXsfqn%2F-Miv0tDivBeetu92XFBd%2Fimage.png?alt=media\&token=452e94c7-e8b5-4bb2-84d4-03f32e288c4d)

### Templates Compatibility

For best compatibility, each template's fields must have similar types. i.e. a field named `text_1` must be of type `textbox` in all the templates.

## Endpoints

{% hint style="info" %}
Collection endpoint only available in asynchronous mode. 
{% endhint %}

## Create images from a template collection

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

Create images from a template collection. This endpoint returns immediately. \
\
To get the images, you can specify a `webhook_url` or poll the collection endpoint.

#### Request Body

| Name          | Type   | Description                                                                                                        |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| select        | number | <p>Select <code>n</code> number of templates randomly from the collection.<br><br>Leave blank to generate all.</p> |
| metadata      | object | Additional metadata that you want to add. This will be returned when the images are ready.                         |
| webhook\_url  | string | Webhook URL to call when the image is ready                                                                        |
| modifications | array  | Array of modifications. Similar to modifications in  Images section.                                               |
| collection    | string | Collection ID                                                                                                      |

{% tabs %}
{% tab title="200 When the images are ready, the status field is set to completed. Otherwise, it is pending." %}

```javascript
{
  "created_at": "2021-09-06T07:10:36.134Z",
  "id": "80b49653-2f71-4c2e-af92-cc861d686993",
  "images": [
    {
      "image_url": null,
      "image_url_jpg": null,
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    }
  ],
  "metadata": null,
  "modifications": [
    {
      "name": "text_1",
      "text": "Hello world"
    },
    {
      "name": "author",
      "text": "Shulhi"
    }
  ],
  "self": "http://api.usestencil.test:4000/v1/collections/80b49653-2f71-4c2e-af92-cc861d686993",
  "status": "pending",
  "templates": [
    {
      "template": "Template 1",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    },
    {
      "template": "Template 2",
      "template_id": "1a7625b3-41ef-4838-9919-c684b98b93b4"
    }
  ],
  "updated_at": "2021-09-06T07:10:39.382Z",
  "webhook_url": null
}
```

{% endtab %}
{% endtabs %}

## Retrieve images from template collection

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

When the images are ready, the `status` field is set to `completed`.

#### Path Parameters

| Name | Type   | Description                                |
| ---- | ------ | ------------------------------------------ |
| id   | string | The ID returned from previous POST request |

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

```javascript
{
  "created_at": "2021-09-06T07:10:36.134Z",
  "id": "80b49653-2f71-4c2e-af92-cc861d686993",
  "images": [
    {
      "image_url": "https://cdn.usestencil.com/images/4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7/ff6a4383-c35e-430f-b5d5-af124cf28a11.png",
      "image_url_jpg": "https://cdn.usestencil.com/images/4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7/ff6a4383-c35e-430f-b5d5-af124cf28a11.jpeg",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    }
  ],
  "metadata": null,
  "modifications": [
    {
      "name": "text_1",
      "text": "Hello world"
    },
    {
      "name": "author",
      "text": "Shulhi"
    }
  ],
  "self": "http://api.usestencil.test:4000/v1/collections/80b49653-2f71-4c2e-af92-cc861d686993",
  "status": "completed",
  "templates": [
    {
      "template": "Template 1",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    },
    {
      "template": "Template 2",
      "template_id": "1a7625b3-41ef-4838-9919-c684b98b93b4"
    }
  ],
  "updated_at": "2021-09-06T07:10:39.382Z",
  "webhook_url": null
}
```

{% endtab %}
{% endtabs %}