# API reference

> Learn how to call the Bannerify REST API to generate images and PDFs from templates.

Canonical: https://bannerify.co/docs/api-reference/overview

The Bannerify API turns a template and a set of values into an image or a PDF. You send a template id and the values to change, and the response is the file. You can also ask for a hosted URL, build signed image URLs, and list your templates.

## Base URL

```plaintext
https://api.bannerify.co
```

Every endpoint lives under `/v1`.

## Endpoints

| Method | Path | Use it to |
| --- | --- | --- |
| `POST` | [`/v1/templates/createImage`](https://bannerify.co/docs/api-reference/endpoint/create-image) | Get an image |
| `POST` | [`/v1/templates/createStoredImage`](https://bannerify.co/docs/api-reference/endpoint/create-stored-image) | Get a hosted image URL |
| `POST` | [`/v1/templates/createPdf`](https://bannerify.co/docs/api-reference/endpoint/create-pdf) | Get a PDF |
| `POST` | [`/v1/templates/createStoredPdf`](https://bannerify.co/docs/api-reference/endpoint/create-stored-pdf) | Get a hosted PDF URL |
| `GET` | [`/v1/templates/signedurl`](https://bannerify.co/docs/api-reference/endpoint/signed-url) | Render an image from a signed URL |
| `GET` | [`/v1/templates`](https://bannerify.co/docs/api-reference/endpoint/template-list) | List your templates |
| `GET` | [`/v1/templates/:id`](https://bannerify.co/docs/api-reference/endpoint/template-details) | Get one template with its layers |
| `GET` | [`/v1/info`](https://bannerify.co/docs/api-reference/endpoint/info) | Check which workspace a key belongs to |

## Make your first request

You need an [API key](https://bannerify.co/docs/api-reference/authentication) and a template id.

```bash
curl --request POST \
  --url https://api.bannerify.co/v1/templates/createImage \
  --header 'Content-Type: application/json' \
  --output banner.png \
  --data '{
    "apiKey": "YOUR_API_KEY",
    "templateId": "tpl_xxx",
    "modifications": [
      { "name": "headline", "text": "Hello from the API" }
    ]
  }'
```

The response body is the image, and `banner.png` now holds it. [Generate images](https://bannerify.co/docs/essentials/generate-images) explains the options.

## How requests and responses work

- `POST` endpoints take a JSON body. Send the `Content-Type: application/json` header with it.
- `GET` endpoints take query parameters.
- A render endpoint waits for the render and returns the file in the same response. A stored endpoint returns JSON with the `url` of the file.
- A failed request returns a JSON `error` object. [Handle errors](https://bannerify.co/docs/api-reference/errors/introduction) lists the codes.
- Every response carries an `X-Request-Id` header. Send that value to support when you need help with a request.
- The API sends `Access-Control-Allow-Origin: *`, but your API key travels in the request, so call the API from a server and not from a browser. A [signed URL](https://bannerify.co/docs/essentials/signed-urls) is the way to show an image in a browser.

## Limits

Each API key can send 100 requests every 10 seconds to a group of render endpoints, and each workspace has a daily or monthly generation limit. [Quota and limits](https://bannerify.co/docs/account/quota) has the details.

## SDKs

Official SDKs for [JavaScript](https://bannerify.co/docs/sdk/js/overview), [Python](https://bannerify.co/docs/sdk/python/overview), [PHP](https://bannerify.co/docs/sdk/php/overview), and [Go](https://bannerify.co/docs/sdk/go/overview) send these requests for you.

## Related

- [Next: Authenticate requests](https://bannerify.co/docs/api-reference/authentication)
- [Documentation index](https://bannerify.co/docs/llms.txt)