# RenderStack API Reference

## Authentication

All API requests require an API key passed in the `X-API-Key` header. Create keys with different permission levels in the API Keys section of the dashboard.

### Permission Levels

| Level | Description |
|-------|-------------|
| Master | Full access to all API endpoints |
| Project | Scoped to specific templates |
| Read-only | View templates and render history only |
| GET | Dynamic URL embedding only (query parameter auth) |

## Endpoints

### Synchronous Render

Renders an image or PDF and returns the binary output directly.

```
POST /api/v1/renders/sync
```

**Headers:**
- `X-API-Key: your_api_key`
- `Content-Type: application/json`

**Request Body:**
```json
{
  "templateId": "tmpl_abc123",
  "overrides": {
    "title": { "text": "Hello World" },
    "avatar": { "src": "https://example.com/photo.jpg" },
    "badge": { "visible": false }
  },
  "format": "png",
  "quality": 90,
  "width": 1200,
  "height": 630
}
```

**Response:** Binary image/PDF data with appropriate Content-Type header.

### Asynchronous Render

Queues a render and returns a render ID for status polling.

```
POST /api/v1/renders
```

Same request body as synchronous render. Returns a render object with status and ID.

### Dynamic Image URL (GET)

Renders an image via URL query parameters. Designed for embedding in HTML img tags.

```
GET /api/v1/render?template=my-template&key=rs_get_xyz&title.text=Hello&title.fill=%23ff0000
```

**Query Parameters:**
- `template` — Template slug or ID
- `key` — GET-scoped API key
- `format` — Output format (png, jpeg, pdf)
- `width` / `height` — Override dimensions
- `[layer].[property]` — Dot-notation layer overrides

**Response:** Binary image data.

## Layer Override Properties

| Property | Type | Description |
|----------|------|-------------|
| `text` | string | Text content for text elements |
| `src` | string | Image URL for image elements |
| `fill` | string | Fill color (hex, rgb, rgba) |
| `stroke` | string | Stroke/border color |
| `visible` | boolean | Show or hide the element |
| `opacity` | number | Element opacity (0-1) |
| `fontSize` | number | Font size in pixels |
| `fontWeight` | string | Font weight (bold, normal, etc.) |
| `data` | string | QR code data/URL |

## Render Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `format` | string | `png` | Output format: png, jpeg, or pdf |
| `quality` | number | `90` | JPEG quality 1-100 |
| `width` | number | template width | Override output width |
| `height` | number | template height | Override output height |
| `sizes` | array | — | Array of {width, height} for multi-page PDF (max 50) |
| `uploadToS3` | boolean | `false` | Auto-upload to configured S3 bucket |

## Response Headers

Render responses include these headers:

| Header | Description |
|--------|-------------|
| `X-Render-Duration-Ms` | Time taken to render in milliseconds |
| `X-Render-Warnings` | JSON array of non-fatal warnings |
| `X-Render-Id` | Unique render identifier |

## Rate Limits

- 60 requests per minute per API key
- 30 requests per minute per IP address
- Cache hits count at reduced weight
- Rate limit headers included in all responses

## Error Handling

RenderStack uses non-blocking rendering. If a specific element fails (broken image URL, invalid QR data), the render continues and warnings are reported in the response headers. Only authentication failures, invalid templates, or server errors produce HTTP error responses.