API Endpoints

To assist others who are building out features for the site, all the endpoints are described below.

Base URL

The Base URL is still our old developmental server. As we migrate the API, this document will change.


Public Endpoints

Public endpoints are visible to everyone using the website.

  • No Authentication
  • Cached results (up to 5 minutes)
  • Objects may not contain all properties (ex: user objects)
    • Look for the lock symbol in the object definitions below.
[ { "id": "test", "fonts": [ { "test": 1 } ] } ]

Get List of Packages

GET /packages

A package is a named grouping of icons. Example: Material Design Icons. This endpoint lists the packages, but leaves off the icons object for performance reasons.

Get Package By Id

GET /package/:packageId

Search through a package of icons.

Get Icon by Id

GET /icon/:iconId

Retrieve a single icon and all public properties at once. Note looping this is very slow as it uses no cache layer to ensure the latest data.

Get Icon by Name

GET /package/:packageId/:iconName

Icon names are unique across a package. This means a package id is also required when making the request as icons across packages share names.

Get Tags

GET /:packageId/tag

A list of tags used to group icons in the system. If count is 0 the item will not be returned.

Get Users

GET /user GET /package/:packageId/user GET /package/:packageId/user/core

Retrieve all users. An alternative is to get users for only a single package or just the core users assigned to maintain that package.

Get User by Id

GET /user/:userId GET /package/:packageId/user/:userId

Retrieve a single user (aka contributor). Using the alternative url with packageId will filter the iconCount to a specific packageId.

Get Styles

GET /:packageId/style

Styles are documented in the icon naming guidelines. Examples include box, circle, outline, off. This endpoint requires the packageId so that it can return the count of each style.

Get Base Icons by Id

GET /icon/:baseIconId/base

A base icon is the most primative version of an icon. For instance account-plus has the base icon of account. This endpoint will retrieve all the icons with the same baseIconId.

Download Icon

POST /download

This endpoint is overloaded to allow downloading a single icon or a package of icons as a zip archive.

Get List of Users by PackageId

GET /package/:packageId/user

List all user objects associated to a packageId.

Private Endpoints

While pretty much all data is open to the public, most of the management related API's are restricted to collaborator and admin accounts.

Get Admin Package Fonts

GET /admin/package/:package_id/font

Retrieve an array of fonts for a given package.

Get Admin Icon Modifications

GET /admin/icon/:iconId/modification

Every modification to an icon property is tracked. This returns a list of those modifications.

isVisible = false hides a modification from the public.

Post Admin Icon Name

POST /admin/icon/name

Update icon.name to rename an icon.

Post Admin Icon Description

POST /admin/icon/description

Update icon.description in a Markdown string.

Post Admin Icon Path Data

POST /admin/icon/data

Update icon.data.

Post Admin Icon Optimize

POST /admin/icon/optimize

Optimize icon.data with SVGO. This is used to preview the change and will not touch the database.

Post Admin Icon Tag

POST /admin/icon/tag

Inserts tag into the database for an icon.

Post Admin Icon Alias

POST /admin/icon/alias

Aliasing icons with alternative names allows others to find them. For example account may also be known as user or person.

Post Admin Icon Style

POST /admin/icon/style

Toggle icon.styles on or off. For instance an icon called account-outline should have the outline style.

Post Admin User

POST /admin/user

Insert a new user into the database. These users are readonly and cannot be logged into.