Docs

API REFERENCE

Colors

A result's colors: read them, recolor it, keep your brand's palettes.

GET/v1/conversions/{id}/paints

The result's paint map

Every tier, like the preview: the paints the file draws with its ground left out, in index order, each with its share of the frame, the ground, and a link to paints.bin: zlib of an index plane then a weight plane (width × height × 4 bytes each: every pixel's four largest paints, 255 = none, and their weights × 255). A pixel of any recolor is Σ w·c′ (premultiplied), with the ground under it as (1 − Σ w)·ground. Made on the first ask; a drawing of more than 24 paints has none.

Path

ididrequired

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
409too_many_colorsRedraw it with fewer colors first.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/paints \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "width": 1,
  "height": 1,
  "ground": "#1f6feb",
  "groundArea": 0,
  "paints": [
    {
      "key": "#1f6feb",
      "area": 0
    }
  ],
  "map": "https://files.vecsnap.com/…",
  "expiresIn": 1
}

GET/v1/conversions/{id}/palette

Preview fewer colors

Previews of a redraw with fewer colors. Without count: the WHOLE rail in one answer (counts), every count in the engine's bounds, colors only: what a client asks once, then reads. With count: the colors the engine REACHES for at most that many (from the result's kept original; it can be fewer), and the result's own colors MERGED into them (mapping), a recolor of the very drawing a client draws exactly. With format (a web file with a picture), also picture: the merged drawing at the preview's size; its deeper tiles are POST /conversions/{id}/tiles with palette. The redraw itself (POST /images/{id}/conversions with options.maxColors) traces new shapes.

Path

ididrequired

Query

countinteger, 2 to 24
One count; left out, the whole rail.
formatstring
With count, a web file's id: its merged picture too.

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409original_not_keptUpload the file again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/palette \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "counts": [
    {
      "asked": 0,
      "count": 1,
      "colors": [
        "#1f6feb"
      ],
      "mapping": {}
    }
  ]
}

GET/v1/conversions/{id}/variants

List a result's recolors

The result's recolors, the last used first: the 10 used last, in one page (hasMore says older ones exist; they are not listed, and saving one again brings it first).

Path

ididrequired

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/variants \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "colors": {},
      "usedAt": "2026-10-24T12:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

POST/v1/conversions/{id}/variants

Recolor a result

colors maps the file's own colors to new ones, every use of each (fills, strokes, gradient stops, the ground); two to one value merge them. Keys are the result's paints and its ground (/facts); the mapping is stored canonical, and the same one saved again is the same variant, used now. Free; its files download under the image's unlock (/download?variant=).

Path

ididrequired

Body

colorsobjectrequired
{"#old": "#new"}, each #rrggbb.

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl -X POST https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/variants \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"colors":{}}'
example answers
{
  "id": "00000000-0000-4000-8000-000000000000",
  "colors": {},
  "usedAt": "2026-10-24T12:00:00.000Z"
}

GET/v1/palettes

List palettes

The account's palettes, the last changed first: at most 20, in one page.

Errors

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/palettes \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
200
example answers
{
  "object": "list",
  "data": [
    {
      "object": "palette",
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Brand colors",
      "colors": [
        "#1f6feb"
      ],
      "updatedAt": "2026-10-24T12:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

POST/v1/palettes

Save a palette

A new palette; an account keeps at most 20 (409 palette_limit).

Body

namestringrequired
Trimmed.
colorsarray of stringrequired
#rrggbb, either case; a repeated one is kept once.

Errors

StatusCodeWhat to do
409palette_limitDelete a palette, then save the new one.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl -X POST https://api.vecsnap.com/v1/palettes \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Brand colors","colors":["example"]}'
example answers
{
  "object": "palette",
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "Brand colors",
  "colors": [
    "#1f6feb"
  ],
  "updatedAt": "2026-10-24T12:00:00.000Z"
}

PATCH/v1/palettes/{id}

Change a palette

Its name and colors, whole. Another's is 404 palette_not_found, the same as none.

Path

ididrequired

Body

namestringrequired
Trimmed.
colorsarray of stringrequired
#rrggbb, either case; a repeated one is kept once.

Errors

StatusCodeWhat to do
404palette_not_foundUse a palette id GET /palettes listed.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl -X PATCH https://api.vecsnap.com/v1/palettes/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Brand colors","colors":["example"]}'
example answers
{
  "object": "palette",
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "Brand colors",
  "colors": [
    "#1f6feb"
  ],
  "updatedAt": "2026-10-24T12:00:00.000Z"
}

DELETE/v1/palettes/{id}

Delete a palette

Removed for good. Another's is 404 palette_not_found, the same as none.

Path

ididrequired

Errors

StatusCodeWhat to do
404palette_not_foundUse a palette id GET /palettes listed.

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl -X DELETE https://api.vecsnap.com/v1/palettes/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "id": "00000000-0000-4000-8000-000000000000",
  "deleted": true
}