Customiser icons

Preview an icon

Copy page

POST/api/v3/customisers/{customiser_id}/icons/preview

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.

Preview an icon

Overview

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.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:read

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

Request body

svgstringbody

Request body example

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

Preview an icon

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>"
}'

{
  "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"
  }
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}