Rendering an image or PDF

Basics

Rendering an image or PDF is as simple as sending a POST request to the /render endpoint. Pass your API key as the Authorization header. The request body may differ slightly depending on the type of document you want to render. To generate a PDF, pass 'pdf' as the type property, otherwise use 'png' or 'jpeg' for images. Renders are saved directly to AWS S3 and their public URLs are returned as JSON by the API.

Request body

In the POST request body, you can pass the following:

Example request

javascript
Copy
const body = {
  type: 'png',
  width: 400,
  height: 350,
  transparent: true,
  html: "<div class='p-4 text-center text-gray-800 text-lg rounded-md bg-white'>{{ title }}</div>",
  props: {
    title: 'A super basic card with Tailwind CSS'
  }
};
const response = await fetch('https://api.tailrender.com/render', {
  method: 'POST',
  headers: {
    Authorization: "{{ YOUR_API_KEY }}",
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});
const json = response.json();

Passing properties

The template API supports passing properties to the render. Properties are passed to the template as a JSON object. Use the props field to pass properties to the render. The API uses Mustache under the hood to render the template. See the Mustache documentation for more information on how to use Mustache syntax. Additionally, any props passed to the render will appear on the render result object. This is useful when attempting to associate render webhooks received from the API.

Webhooks

Instead of synchronous generation, you can choose to have your render result delivered via webhook instead. To use webhook delivery, specify the webhook URL using the webhookUrl field. The API will respond with a 202 Accepted status code when your render request is received. When the render is complete, the API will deliver a POST request to the webhook URL with the render result payload. Three attempts will be made to deliver the webhook, each with a delay of 15 seconds between requests, before declaring the result undeliverable.

Supplemental CSS

You can pass supplemental CSS to the render by passing a css property. If you pass a css property, you must include the base TailwindCSS utility classes along with any custom CSS you want to use. For example, if you want to use the b-green CSS class, you must include the following:

css
Copy
@tailwind base;
@tailwind components;
@tailwind utilities

.b-green {
  @apply text-green-500 font-bold;
}

Failing to specify the base TailwindCSS utility classes will prevent the API from compiling the CSS properly.

Tailwind CSS Config

The tailwindConfig property is an object that contains the TailwindCSS configuration. The default configuration is included in as a part of every request. Plugins are currently unsupported by the API, although we do support the official TailwindCSS plugins. See the TailwindCSS documentation for more information.

Example response body

json
Copy
{
    "id": "r5mT9aAuUhstaJYBNGcJ",
    "templateName": "resume-template",
    "status": "COMPLETED",
    "result": {
        "pdfUrl": "https://tailrender-api.s3.amazonaws.com/pdf/r5mT9aAuUhstaJYBNGcJ.pdf",
        "url": "https://tailrender-api.s3.amazonaws.com/pdf/r5mT9aAuUhstaJYBNGcJ.pdf"
    },
    "props": {
        "phone": "(555) 234-2344",
        "email": "jane.smith@gmail.com"
    }
}

Errors

You may receive an error while attempting to render your file. Errors while generating files are quite rare, however, if the error persists, please contact support.

A file generation error might look like the following:

json
Copy
{
    "id": "lhXcGjxf63vq27odmqCb",
    "status": "ERROR",
    "error": "An unknown error occurred while attempting to generate this file."
}