# QuickChart Agent Notes

QuickChart is an HTTP API for generating static images of Chart.js charts, word clouds, tables, QR codes, barcodes, and watermarked images. It is commonly used in email, SMS, PDFs, chatbots, automation tools, and reports where client-side rendering is not available.

## Request guidance

- Prefer POST JSON for generated chart configs. GET URLs are useful for small hand-written examples, but agents often produce configs that are too long or need URL encoding.
- Validate before retrying. Use /api/validate-chart for chart configs and /api/validate-qr for QR payloads to get structured JSON errors.
- Use /openapi.json for parameter names, response types, and limits.
- For charts, send Chart.js config in the chart field. If the config contains Javascript functions, send chart as a string.
- For Graphviz/DOT diagrams, use /graphviz and send DOT input in the graph field, not the chart field.
- Use /wordcloud for word-frequency visualizations and /v1/table for portable PNG tables; both support POST JSON when a GET URL would be too long.
- Use /watermark to compose two public image URLs. It returns PNG even when the source images use other formats.
- Use /gchart only for Google Image Charts compatibility. Prefer /chart, /graphviz, or /qr for new integrations.
- /qr-url and /qr-urls return JSON containing image URLs; /qr and /qr/batch return rendered image data.
- Set version to "4" for Chart.js v4 syntax. The default is Chart.js v2.
- Set format to png unless the caller asks for svg, webp, jpg, pdf, or base64.
- Include width and height explicitly when output dimensions matter. Charts default to devicePixelRatio=2; use 1 for the exact requested pixel dimensions. Fractional ratios up to 2 are supported.
- Use Authorization: Bearer YOUR_API_KEY or the key field for authenticated requests.

## Chart examples

POST https://quickchart.io/api/validate-chart

```json
{
  "version": "4",
  "width": 700,
  "height": 360,
  "format": "png",
  "chart": {
    "type": "bar",
    "data": {
      "labels": ["Jan", "Feb", "Mar"],
      "datasets": [{ "label": "Revenue", "data": [120, 150, 180] }]
    }
  }
}
```

POST https://quickchart.io/chart with the same body to receive image bytes. Check validation warnings even when success is true: v3/v4 options sent with the default v2 version can be ignored. Chart validation checks the underlying render but does not perform the final JPEG, WebP, or PDF conversion.

## Graphviz examples

POST https://quickchart.io/graphviz

```json
{
  "graph": "digraph G { A -> B }",
  "format": "svg",
  "engine": "dot"
}
```

GET https://quickchart.io/graphviz is also supported with graph, format, engine, width, and height query parameters.

## Word cloud examples

POST https://quickchart.io/wordcloud

```json
{
  "text": "reliable APIs make automation reliable",
  "format": "png",
  "width": 800,
  "height": 400,
  "scale": "sqrt",
  "removeStopwords": true
}
```

The response is SVG by default or PNG when format is png. Set useWordList to true to send comma-separated words or weighted entries such as reliable:3,automation:2.

## Table image examples

POST https://quickchart.io/v1/table

```json
{
  "data": {
    "title": "Quarterly revenue",
    "columns": [
      { "title": "Quarter", "dataIndex": "quarter", "width": 120 },
      { "title": "Revenue", "dataIndex": "revenue", "width": 140, "align": "right" }
    ],
    "dataSource": [
      { "quarter": "Q1", "revenue": "$120k" },
      { "quarter": "Q2", "revenue": "$150k" }
    ]
  },
  "options": {
    "paddingHorizontal": 20,
    "paddingVertical": 20,
    "backgroundColor": "#ffffff"
  }
}
```

The response is a PNG image. GET is also supported when data and options are URL-encoded JSON query parameters.

## Watermark examples

POST https://quickchart.io/watermark

```json
{
  "mainImageUrl": "https://example.com/chart.png",
  "markImageUrl": "https://example.com/logo.png",
  "position": "bottomRight",
  "markRatio": 0.2,
  "opacity": 0.6
}
```

Both source URLs must be publicly reachable. The response is a PNG image.

## QR examples

POST https://quickchart.io/api/validate-qr

```json
{
  "text": "https://example.com",
  "format": "png",
  "size": 300,
  "margin": 4
}
```

POST https://quickchart.io/qr with the same body to receive image bytes. Captions work with PNG, JPEG, SVG, and base64 output, including styled QR codes. Center images require PNG, JPEG, or base64 output.

To construct URLs without rendering, POST the QR parameters to /qr-url. For multiple URLs, POST { "qrCodes": [{ "text": "first" }, { "text": "second" }] } to /qr-urls. These endpoints return { "url": "..." } and { "urls": ["..."] } respectively; use /qr/batch when you need rendered files in a ZIP.

## Barcode examples

POST https://quickchart.io/barcode

```json
{
  "type": "code128",
  "text": "ABC-1234",
  "format": "png",
  "includeText": true
}
```

The type field selects the symbology (for example code128, ean13, upca, qrcode). The response is image bytes.

## Google Image Charts compatibility

GET https://quickchart.io/gchart?cht=bvg&chs=300x200&chd=t:10,20,30

This endpoint accepts legacy Google Image Charts query parameters. Use it when migrating an existing integration; use /chart for new Chart.js requests. The full compatibility parameter reference is linked from /openapi.json.

## QR reading

POST https://quickchart.io/qr-read

```json
{
  "url": "https://example.com/qr.png"
}
```

Send url to fetch and decode a remote image, or image with raw base64 data (without a data URI prefix). GET /qr-read?url=... also works. PNG, JPEG, BMP, TIFF, and GIF are supported. Missing input returns 400; fetch and decoding failures return 500 with an error string. The response is JSON in the form { "result": "decoded text" }.

## Natural-language chart generation

POST https://quickchart.io/natural/config

```json
{
  "description": "bar chart showing revenue Jan-Mar with values 120, 150, 180",
  "width": 700,
  "height": 360,
  "backgroundColor": "white"
}
```

The response includes a generated Chart.js config string, a saved chart image URL, and a chart editor URL. Treat generated configs as drafts and validate them before embedding in production workflows.