API reference
Base URL https://www.graphtr.com/api/v1. A machine readable description lives at /api/v1/openapi.json.
POST /designs
Renders a design and returns the file. The response body is image bytes, with Content-Type set to match the format. Add ?response=json to get metadata and a base64 body instead.
POST /api/v1/designsAuthorization: Bearer gt_live_...Content-Type: application/json { "templateId": "poster-live-music", "format": "png", "fill": { "headline": "Live at the Attic", "detail": "Friday, 9 PM" }}Parameters
| Name | Type | Description |
|---|---|---|
| templateId | string | A template id from GET /api/v1/templates. Omit when sending a prompt. |
| prompt | string | What you want made. The model picks a template and writes the copy. |
| fill | object | Copy per slot, keyed by role: headline, subhead, body, cta, price, detail, contact. |
| preset | string | Canvas preset id, for example instagram or poster. Used when no templateId is given. |
| format | string | svg or png. Defaults to svg. |
| brandKitId | string | A brand kit from your account. Recolours and retypes the template. |
One of templateId or prompt is required.
GET /templates
Lists the library. Filter with category, format or q. Each entry carries its dimensions, the slots it accepts and whether your plan can use it, so you never have to discover a paywall by hitting one. Discovery calls do not count against the render allowance.
GET /usage
Your plan, what you have used this period and when it resets.
Errors
Every error is JSON with a stable error code and a message meant for a human.
{ "error": "rate_limited", "message": "You have used this month's render allowance."}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_input | A parameter is missing or malformed. |
| 401 | unauthenticated | No key, or the key is not valid. |
| 403 | forbidden | The key lacks the scope, or the template needs a paid plan. |
| 404 | not_found | No template with that id. |
| 429 | rate_limited | Burst limit or monthly allowance reached. Retry-After is set. |
| 502 | upstream_failure | A model provider failed. The render was not counted. |
Quota headers
Once a key is accepted, every response carries the five headers below, including the 429 that tells you the allowance is gone. Discovery calls carry them too, so an agent can check what it can afford before it spends anything. A rejected key gets a 401 with no quota to report.
| Header | Meaning |
|---|---|
| X-Quota-Limit | Renders included in your plan this month. |
| X-Quota-Used | Renders spent so far this month. |
| X-Quota-Remaining | Renders left before the allowance is gone. |
| X-Quota-Reset | Unix seconds at which the allowance resets. |
| X-RateLimit-Remaining | Requests left in the current burst window. |