Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Icons

Library icons: the icon libraries that ship with the server (Lucide, Font Awesome Free) and the ones an owner makes by uploading icons or importing an Iconify JSON file. Choosing and managing them takes library:manage; the pictures are for anyone who can see a library.

Paths are relative to /api/v1 on your server.

GET/icon-sets#

List icon libraries

The built-in libraries first, by their Iconify prefix (lucide, fa6-solid…), then the custom ones by name.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/icon-sets#

Create an icon library

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 201Success. application/json · IconSet
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/icon-sets/{id}#

Read an icon library and its icons

Every icon, an SVG as its markup and a picture as its URL. id is a built-in prefix or a custom library’s uuid. Compressed when the client accepts br or gzip; answers 304 to a matching If-None-Match.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring
  • 200Success. application/json · IconSetDetail
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PATCH/icon-sets/{id}#

Rename an icon library, or change its tint

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · IconSet
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/icon-sets/{id}#

Delete an icon library

Its icons go with it, and a library that showed one goes back to its type’s drawing.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/icon-sets/{id}/icons#

Upload an icon

The body is the file (1 MB at most): SVG, PNG, JPEG, WebP or GIF, told apart by its bytes. An SVG is rebuilt from an allow-list — shapes and paint, no script, no text, nothing that leaves the icon — and a picture is re-encoded as a PNG of 256 pixels at most. A name already in the library gets -2, -3….

Authorisation
Bearer token or API key · Session cookie
Body
image/* ·
ParameterInTypeDescription
id requiredpathstring (uuid)
name requiredquerystring
  • 201Success. application/json · Icon
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/icon-sets/import#

Import an Iconify JSON file as an icon library

The body is the file itself (application/json, 16 MB at most). Every icon is sanitised as an upload is; one that cannot be drawn safely is skipped and counted, and at most 5,000 are kept. A set that says it is in colour (info.palette) is not tinted.

Authorisation
Bearer token or API key · Session cookie
Body
application/json ·
ParameterInTypeDescription
namequerystring
  • 201Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/icons/{id}#

Serve an uploaded icon

Its bytes never change under its id, so it is cached for good. An SVG is served under a sandboxing Content-Security-Policy.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. image/* ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/icons/{id}#

Delete an uploaded icon

A library that showed it goes back to its type’s drawing.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/icons/builtin/{prefix}/{name}#

Serve a built-in icon

An icon of a built-in library as an SVG, by its Iconify name; an old name a set keeps as an alias still answers.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
prefix requiredpathstring
name requiredpathstring
  • 200Success. image/svg+xml ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope