Developers aka the API page

Client Development

The FrankerFaceZ client can be found at https://github.com/FrankerFaceZ/FrankerFaceZ and is licensed under the Apache License, Version 2.0.

The API v1 - The Bare Bones Release

Base Url
//api.frankerfacez.com/v1/

This API version does not require or support authentication. It returns JSON-formatted data.

GET /badge/:id or GET /badge/:name

Fetch all the relevant data for a chat badge, including the list of users that have that badge.

curl https://api.frankerfacez.com/v1/badge/developer
{
  "badge": {
    "alpha_image": "//cdn.frankerfacez.com/script/devtransicon.png",
    "color": "#FAAF19",
    "css": null,
    "id": 1,
    "image": "//cdn.frankerfacez.com/script/devicon.png",
    "name": "developer",
    "replaces": null,
    "slot": 5,
    "title": "FFZ Developer"
  },
  "users": {
    "1": [
      "sirstendec",
      "dansalvato"
    ]
  }
}

GET /_badge/:id or GET /_badge/:name

Fetch all the relevant data for a chat badge.

curl https://api.frankerfacez.com/v1/_badge/developer
{
  "badge": {
    "alpha_image": "//cdn.frankerfacez.com/script/devtransicon.png",
    "color": "#FAAF19",
    "css": null,
    "id": 1,
    "image": "//cdn.frankerfacez.com/script/devicon.png",
    "name": "developer",
    "replaces": null,
    "slot": 5,
    "title": "FFZ Developer"
  }
}

GET /badges

Fetch all information about all badges. Useful when initializing the client.

curl https://api.frankerfacez.com/v1/badges
{
  "badges": [
    {
      "alpha_image": "//cdn.frankerfacez.com/script/devtransicon.png",
      "color": "#FAAF19",
      "css": null,
      "id": 1,
      "image": "//cdn.frankerfacez.com/script/devicon.png",
      "name": "developer",
      "replaces": null,
      "slot": 5,
      "title": "FFZ Developer"
    },
    {
      "alpha_image":null,
      "color": "#595959",
      "css": null,
      "id": 2,
      "image": "//cdn.frankerfacez.com/script/boticon.png",
      "name": "bot",
      "replaces": "moderator",
      "slot": 1,
      "title": "Bot"
    },
    {
      "alpha_image":null,
      "color": "#755000",
      "css": null,
      "id": 3,
      "image": "//cdn.frankerfacez.com/script/devicon.png",
      "name": "supporter",
      "replaces": null,
      "slot": 5,
      "title": "FFZ Supporter"
    }
  ],
  "users": {
      ...
  }
}

GET /_badges

Fetch information about all badges. Useful when initializing the client. Does not include users.

curl https://api.frankerfacez.com/v1/_badges
{
  "badges": [
    {
      "alpha_image": "//cdn.frankerfacez.com/script/devtransicon.png",
      "color": "#FAAF19",
      "css": null,
      "id": 1,
      "image": "//cdn.frankerfacez.com/script/devicon.png",
      "name": "developer",
      "replaces": null,
      "slot": 5,
      "title": "FFZ Developer"
    },
    {
      "alpha_image":null,
      "color": "#595959",
      "css": null,
      "id": 2,
      "image": "//cdn.frankerfacez.com/script/boticon.png",
      "name": "bot",
      "replaces": "moderator",
      "slot": 1,
      "title": "Bot"
    },
    {
      "alpha_image":null,
      "color": "#755000",
      "css": null,
      "id": 3,
      "image": "//cdn.frankerfacez.com/script/devicon.png",
      "name": "supporter",
      "replaces": null,
      "slot": 5,
      "title": "FFZ Supporter"
    }
  ]
}

GET /emote/:id

Fetch information for a specific emote.

curl https://api.frankerfacez.com/v1/emote/25927
{
  "emote": {
    "css": null,
    "height": 29,
    "hidden": false,
    "id": 25927,
    "margins": null,
    "name": "CatBag",
    "owner": {
      "display_name": "Wolsk",
      "id": 3,
      "name": "wolsk"
    },
    "public": false,
    "urls": {
      "1": "//cdn.frankerfacez.com/emoticon/25927/1",
      "2": "//cdn.frankerfacez.com/emoticon/25927/2",
      "4": "//cdn.frankerfacez.com/emoticon/25927/4"
    },
    "width": 32
  }
}

GET /emoticons

Fetch bulk emote information.

Parameter Default Values Description
high_dpi off on, off Whether or not to only include emotes with high-DPI images.
page 1 1 <= value The page of emotes to return.
per_page 50 1 <= value <= 200 The number of emotes to return on a single page.
private off on, off Whether or not to include non-public emotes.
q     A search string to filter the results.
sort created-desc name, owner, count, updated, created Sort the output. Optionally, include a sorting direction after a hyphen.
Example: sort=count-desc 
curl https://api.frankerfacez.com/v1/emoticons?_sceheme=https
{
  "_links":{
    "next":"http://api.frankerfacez.com/v1/emoticons?page=2",
    "self":"http://api.frankerfacez.com/v1/emoticons?page=1"
  },
  "_pages":1068,
  "_total":53371,
  "emoticons":[
    ...
  ]
}

GET /room/id/:twitch_id or GET /room/:name

Fetch all the relevant data for a chat room, including the emote set associated with the room.

curl https://api.frankerfacez.com/v1/room/sirstendec
{
  "room": {
    "_id": 1,
    "css": null,
    "display_name": "SirStendec",
    "id": "sirstendec",
    "is_group": false,
    "moderator_badge": null,
    "set": 1,
    "twitch_id": 49399878
  },
  "sets": {
    "1": {
      ...
    }
  }
}

GET /_room/id/:twitch_id or GET /_room/:name

Fetch all the relevant data for a chat room but do not include the emote set associated with the room.

curl https://api.frankerfacez.com/v1/_room/dansalvato
{
  "room": {
    "_id": 2,
    "_tid": 47852576,
    "css": null,
    "display_name": "dansalvato",
    "id": "dansalvato",
    "is_group": false,
    "moderator_badge": "//cdn.frankerfacez.com/cdf8b6845ac18d77137001a5be7cd155.png",
    "set": 2
  }
}

GET /set/:id

Fetch all the data for an emote set, including details on every approved emote within the set and a list of users that can use emotes from the set globally.

curl https://api.frankerfacez.com/v1/set/4
{
  "set": {
    "_type": 1,
    "css": null,
    "description": null,
    "emoticons": [
      {
        ...
      },
      ...
    ],
    "icon": null,
    "id": 4,
    "title": "Channel: Wolsk"
  },
  "users": {
    "1": [
      "sirstendec"
    ]
  }
}

GET /set/global

Fetch all sets that could be used globally. That is, sets that aren't associated with specific chat rooms.

Not all users should be able to use all of the sets provided. The default_sets key of the returned object contains a list of set IDs that should be available for all users to use.

A mapping of emote sets to users that should be allowed to use them globally is provided.

curl https://api.frankerfacez.com/v1/set/global
{
  "default_sets": [ 3 ],
  "sets": {
    ...
  },
  "users": {
    "4330": [
      "sirstendec"
    ],
    ...
  }
}

GET /user/id/:twitch_id or GET /user/:name

Get relevant information about a user, including their chat badges and which emote sets they can use globally.

curl https://api.frankerfacez.com/v1/user/sirstendec
{
  "badges": {
    "1": {
      ...
    }
  },
  "sets": {
    "4330": {
      ...
    }
  },
  "user": {
    "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/sirstendec-profile_image-b3577527af5a026f-300x300.png",
    "badges": [ 1 ],
    "display_name": "SirStendec",
    "emote_sets": [ 4330 ],
    "id": 1,
    "is_donor": true,
    "name": "sirstendec",
    "twitch_id": 49399878
  }
}

GET /_user/id/:twitch_id or GET /_user/:name

Get relevant information about a user, not including badge data.

curl https://api.frankerfacez.com/v1/_user/sirstendec
{
  "user": {
    "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/sirstendec-profile_image-b3577527af5a026f-300x300.png",
    "badges": [ 1 ],
    "display_name": "SirStendec",
    "emote_sets": [ 4330 ],
    "id": 1,
    "is_donor": true,
    "name": "sirstendec",
    "twitch_id": 49399878
  }
}