# POST Preview an icon

Shows what the icon converter makes of a drawing before you create an icon from it. The server sanitises the SVG, converts it through the icon service, and sanitises the result again, which is the same pass an icon create or an svg update runs. The answer's `svg` is the drawing the create would store as `rendered_svg`. Nothing is saved: no icon is created, the icon font is not rebuilt, and no idempotency key is used, so the operation is safe to repeat. Requires `customisers:read`. Each call uses the icon service, so the operation has its own per-key limit, separate from the option-write budget. When you exceed it, the answer is a 429 with `retry_after`; wait that many seconds and retry. A drawing that is not a single SVG, or that has nothing left once scripts, event handlers and external references are removed, is a 422 with the error code `invalid_svg` on `/svg`; send a plain vector drawing. A 502 `icon_conversion_failed` means the icon service could not be reached; retry the request.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-preview-an-icon/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-preview-an-icon.md
- Group: Customiser icons
- Method: POST
- Path: /api/v3/customisers/{customiser_id}/icons/preview
- Auth: Bearer token
- Required scopes: `customisers:read`

## Path parameters

- customiser_id (string, required): The customiser id, from the list customisers operation. Example: 1

## Body parameters

- svg (string, optional): No description provided.

## Request body example

```json
{
  "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
}
```

## cURL example

```bash
curl https://web.signcustomiser.com/api/v3/customisers/1/icons/preview \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
}'
```

## Response examples

### 200 POST 200 example 1

```json
{
  "data": {
    "object": "icon_preview",
    "customiser_id": 42,
    "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/icons/preview",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}
```

### 400 Malformed JSON body

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/malformed_json",
  "title": "Malformed JSON",
  "status": 400,
  "code": "malformed_json",
  "detail": "The request body is not valid JSON: Syntax error.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 401 Missing API key

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 403 Insufficient scope

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the customisers:read scope.",
  "required_scopes": [
    "customisers:read"
  ],
  "granted_scopes": [
    "store:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 404 Unknown customiser

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 413 Request body too large

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/request_too_large",
  "title": "Request too large",
  "status": 413,
  "code": "request_too_large",
  "detail": "The request body must not exceed 2 MiB.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 422 Invalid SVG

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The icon SVG could not be sanitised safely: nothing was left of it once scripts, event handlers, and external references were removed. Send a plain vector drawing.",
  "errors": [
    {
      "pointer": "/svg",
      "code": "invalid_svg",
      "detail": "The icon SVG could not be sanitised safely."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 429 Preview limit exceeded

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 42,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 502 Icon converter unavailable

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/icon_conversion_failed",
  "title": "Icon conversion failed",
  "status": 502,
  "code": "icon_conversion_failed",
  "detail": "The icon converter could not prepare this drawing, so nothing was written. The icon service is a separate dependency; retry the request, and contact support if it keeps failing.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```