---
name: cofferdock
description: Create real files from an automation or a conversation with the Cofferdock API. Use when the user wants an image from HTML (social cards, certificates, OG images, posters), a PDF from HTML (invoices, reports), a website screenshot, a QR code, a chart image from data, to edit PDFs (merge, split, rotate, watermark, page numbers, fill forms, extract text, metadata, add or remove a password), to resize or convert images, to build a zip, or to validate emails, phone numbers or IBANs.
---

# Cofferdock

Cofferdock is an HTTP API with 25 tools behind one API key. Base URL: `https://api.cofferdock.com`.
Full, machine-readable reference: `https://cofferdock.com/openapi.json`. Human reference: `https://cofferdock.com/api`.

## Before calling

- The API key goes in the `x-api-key` header. Read it from the environment variable `COFFERDOCK_API_KEY`. If it is not set, ask the user for it and point them to https://cofferdock.com/register (free plan, no card). Never print the key or write it into files.
- Each successful call uses 1 credit from the user's monthly plan. Failed calls are free. Check the balance with `GET /status` before long batches.
- If the Cofferdock MCP server is connected (tools such as `html_to_image`), prefer those tools over raw HTTP.

## Choosing the output

Every tool that returns a file accepts `output`:

- `url`: JSON with a temporary download link valid 15 minutes. Best default when you only need to hand the file to the user.
- `binary`: the file itself in the response body. Best when saving to disk: `curl ... -o file.png`.
- `json`: the file as base64 inside JSON, plus metadata.

## Recipes

HTML to image (inline CSS; web fonts and https images allowed; JavaScript is not executed):

```bash
curl -s -X POST https://api.cofferdock.com/capture \
  -H "x-api-key: $COFFERDOCK_API_KEY" -H "Content-Type: application/json" \
  -d '{"html":"<div style=\"width:1080px;height:1080px;display:flex;align-items:center;justify-content:center;background:#f2a93b;font:700 96px sans-serif\">20% OFF</div>","width":1080,"height":1080,"format":"png","output":"binary"}' \
  -o card.png
```

HTML to PDF:

```bash
curl -s -X POST https://api.cofferdock.com/pdf \
  -H "x-api-key: $COFFERDOCK_API_KEY" -H "Content-Type: application/json" \
  -d '{"html":"<h1>Invoice #1001</h1><p>Total: 120.00 EUR</p>","format":"A4","margin":15,"output":"binary"}' \
  -o invoice.pdf
```

Send an existing PDF raw (options as query parameters):

```bash
curl -s -X POST "https://api.cofferdock.com/pdf-page-numbers?format=Page%20%7Bn%7D%20of%20%7Btotal%7D&output=binary" \
  -H "x-api-key: $COFFERDOCK_API_KEY" -H "Content-Type: application/pdf" \
  --data-binary @report.pdf -o report-numbered.pdf
```

Several files in JSON (base64): `POST /pdf-merge` with `{"files": ["<base64>", "<base64>"], "output": "binary"}`.

Chart from data: `POST /chart` with `{"type":"bar","labels":["Jan","Feb"],"series":[{"name":"Sales","data":[120,90]}],"output":"binary"}`.

## Designing good HTML for images

- Set the size of the outer element to exactly the `width` and `height` you request, and `margin:0` on `body`.
- Use system fonts or Google Fonts via `<link>`; wait briefly with `wait_ms: 500` if a web font must load.
- Keep contrast high and text large: images are usually viewed small.

## Errors

- `400`: invalid input; read `error`, fix it and retry. Nothing was charged.
- `401` / `403`: missing or invalid key, or the account email is not verified.
- `429`: monthly credits used up (`Monthly limit reached`) or too many calls per minute for the plan. Respect `Retry-After`.
- `503`: server busy. Wait the seconds in `Retry-After` and retry.