Public API

Kicklet's HTTP API is available below /api on the same host as the dashboard. The production base URL is:

Transitional API

This is not Kicklet's final stable public API. These endpoints document the HTTP routes that are currently available for integrations and dashboard-adjacent automation. Paths, permissions, request bodies, and response formats may change while Kicklet's dedicated public API is still being designed.

https://kicklet.app/api

Use the API when an external tool should read channel data, send chat messages, update points, manage variables, or connect Kicklet to another system. Some endpoints are public read endpoints, but most endpoints require an API token because they act on your Kicklet account.

Authentication

Create API tokens in Profile / Settings. Send the token in the Authorization header:

Authorization: APIToken YOUR_TOKEN

Use a separate token per integration and only enable the permissions that integration needs. Treat the token like a password. A leaked token can be revoked without changing your Kicklet login.

The examples below include an API token field for authenticated endpoints. The token is only kept in your browser for the current docs session.

IDs

Some endpoints use userId, and some use kickId.

• userId is the Kicklet account ID returned by user lookup endpoints and used by account-owned resources such as commands, variables, counters, and song requests.
• kickId is the Kick user ID used by stats endpoints.

You can look up both IDs from a Kick username.

GET/user/by-kick-username/{kickUsername}

Find a Kicklet user by Kick username

Returns the Kicklet account ID and Kick user ID for a public Kicklet account.

Base URL

Kick username

Requesthttps://kicklet.app/api/user/by-kick-username/kicklet

Example response

{
  "id": 123,
  "kickId": 456789,
  "kickUsername": "Kicklet",
  "kickSlug": "kicklet"
}

Public Read Endpoints

These endpoints do not require an API token. They are intended for overlays, public profile pages, and read-only integrations.

GET/stats/public/{kickId}/viewer/ranking

Public viewer ranking

Returns public viewer ranking data. Use search to find one viewer by username, or order the list by watchtime, points, or messagesSent.

Base URL

Kick IDpagepageSizeorderByordersearch

Requesthttps://kicklet.app/api/stats/public/%7BkickId%7D/viewer/ranking?page=1&pageSize=10&orderBy=watchtime&order=desc

Example response

{
  "count": 1,
  "ranking": [
    {
      "viewerKickUserID": 324342,
      "viewerKickUsername": "Test",
      "watchTime": 466321367161466,
      "points": 5000,
      "messagesSent": 4700,
      "rank": 6
    }
  ]
}

GET/stats/public/{kickId}/currency

Public point currency

Returns the configured name of the channel point currency.

Base URL

Kick ID

Requesthttps://kicklet.app/api/stats/public/%7BkickId%7D/currency

Example response

{
  "currency": "points"
}

GET/song/public/{userId}

Public song queue

Returns the public song request queue for a Kicklet account.

Base URL

Kicklet user ID

Requesthttps://kicklet.app/api/song/public/%7BuserId%7D

Chat

Chat endpoints act as Kicklet in your Kick chat. They require an API token for the owner account.

POST/kick/message

Send a Kick chat message

Sends a message to the connected Kick chat as Kicklet.

Base URLAPI tokenJSON body{ "content": "Hello from the Kicklet API" }

Requesthttps://kicklet.app/api/kick/message

Example response

{
  "id": "f28bcec7-8825-422a-aa9c-e24d0fddf388",
  "content": "Hello from the Kicklet API"
}

POST/kick/chat/clear

Clear chat

Clears the connected Kick chatroom.

Base URLAPI token

Requesthttps://kicklet.app/api/kick/chat/clear

POST/kick/chat/follower

Set follower-only mode

Turns follower-only mode on or off. minDuration is the required follow duration in minutes.

Base URLAPI tokenJSON body{ "on": true, "minDuration": 10 }

Requesthttps://kicklet.app/api/kick/chat/follower

POST/kick/chat/subscriber

Set subscriber-only mode

Turns subscriber-only chat mode on or off.

Base URLAPI tokenJSON body{ "on": true }

Requesthttps://kicklet.app/api/kick/chat/subscriber

POST/kick/chat/emote

Set emote-only mode

Turns emote-only chat mode on or off.

Base URLAPI tokenJSON body{ "on": true }

Requesthttps://kicklet.app/api/kick/chat/emote

POST/kick/chat/slow

Set slow mode

Turns slow mode on or off. messageInterval is the delay between messages in seconds.

Base URLAPI tokenJSON body{ "on": true, "messageInterval": 10 }

Requesthttps://kicklet.app/api/kick/chat/slow

DELETE/kick/chat/restrictions

Clear chat restrictions

Removes active chatroom restrictions.

Base URLAPI token

Requesthttps://kicklet.app/api/kick/chat/restrictions

Viewer stats and points

Stats endpoints use kickId. Reading stats requires stats.view; changing points or viewer stats requires stats.update.

GET/stats/{kickId}/viewer/ranking

Viewer ranking

Returns the private viewer ranking including last activity. Use the same ordering and search fields as the public ranking endpoint.

Base URLAPI token

Kick IDpagepageSizeorderByordersearch

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/ranking?page=1&pageSize=10&orderBy=watchtime&order=desc

GET/stats/{kickId}/viewer/{viewer}/stats

Viewer stats

Returns points, watchtime, message count, rank, and last activity for one viewer.

Base URLAPI token

Kick IDViewer username

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/%7Bviewer%7D/stats

PATCH/stats/{kickId}/viewer/{viewer}/stats

Update viewer stats

Replaces the selected viewer stats with exact values. watchTime is stored as a duration value in nanoseconds.

Base URLAPI token

Kick IDViewer username

JSON body{ "points": "1000", "watchTime": "3600000000000", "messagesSent": "50" }

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/%7Bviewer%7D/stats

POST/stats/{kickId}/viewer/reset

Reset viewer stats

Resets selected viewer stat fields for the channel. Set only the fields you want to reset to true.

Base URLAPI token

Kick ID

JSON body{ "origin": false, "points": true, "watchTime": false, "messagesSent": false }

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/reset

Get viewer points with the API

GET/stats/{kickId}/points/{viewer}

Get viewer points

Reads the current point balance for one viewer.

Base URLAPI token

Kick IDViewer username

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/points/%7Bviewer%7D

Add points with the API

PATCH/stats/{kickId}/points/{viewer}/add/{points}

Add points

Adds points to one viewer and returns the updated value.

Base URLAPI token

Kick IDViewer usernamepoints

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/points/%7Bviewer%7D/add/12

Remove points with the API

PATCH/stats/{kickId}/points/{viewer}/remove/{points}

Remove points

Subtracts points from one viewer.

Base URLAPI token

Kick IDViewer usernamepoints

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/points/%7Bviewer%7D/remove/12

Set viewer points with the API

PATCH/stats/{kickId}/points/{viewer}/set/{points}

Set points

Sets one viewer's balance to an exact value.

Base URLAPI token

Kick IDViewer usernamepoints

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/points/%7Bviewer%7D/set/1000

Add points to active viewers with the API

PATCH/stats/{kickId}/points/add-viewer/{points}

Add points to active viewers

Adds points to every viewer Kicklet currently considers active in chat.

Base URLAPI token

Kick IDpoints

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/points/add-viewer/10

Get point settings with the API

GET/stats/{kickId}/settings/points

Get point settings

Reads the channel point configuration, including currency name and automatic earning settings.

Base URLAPI token

Kick ID

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/settings/points

Live and Activity Stats

Use these endpoints for dashboards, overlays, and external automations that need current channel activity.

GET/stats/{kickId}/watchtime/{viewer}

Viewer watchtime

Returns the tracked watchtime for one viewer.

Base URLAPI token

Kick IDViewer username

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/watchtime/%7Bviewer%7D

GET/stats/{kickId}/viewer/active/count

Active viewer count

Returns how many viewers are currently considered active by Kicklet.

Base URLAPI token

Kick ID

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/active/count

GET/stats/{kickId}/viewer/active/random

Random active viewers

Returns up to max random active viewers.

Base URLAPI token

Kick IDmax

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/viewer/active/random?max=10

GET/stats/{kickId}/livestream/is-live

Live status

Returns whether the channel is currently live.

Base URLAPI token

Kick ID

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/livestream/is-live

GET/stats/{kickId}/livestream

Livestream history

Returns a paginated list of tracked livestreams with stream stats.

Base URLAPI token

Kick IDpagepageSize

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/livestream?page=1&pageSize=10

GET/stats/{kickId}/last-events

Recent events

Returns recent channel events such as follows, subscriptions, and related stream events.

Base URLAPI token

Kick ID

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/last-events

GET/stats/{kickId}/events

Event list

Returns a searchable, paginated event list. typeFilters accepts comma-separated event types.

Base URLAPI token

Kick IDpagepageSizeorderByordersearchtypeFilters

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/events?page=0&pageSize=10&order=desc

GET/stats/{kickId}/subscriptions/active

Active subscriptions

Returns active subscriptions for the channel.

Base URLAPI token

Kick IDpagepageSize

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/subscriptions/active?page=0&pageSize=10

Command Stats

Command stats can be used for overlays, analytics, or external automations that react to command usage.

GET/stats/{kickId}/command/execution/count

Total command executions

Returns the total command execution count for the last number of minutes.

Base URLAPI token

Kick IDminutes

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/command/execution/count?minutes=60

GET/stats/{kickId}/command/{command}/execution/count

One command execution count

Returns the execution count for one command during the selected time window.

Base URLAPI token

Kick IDcommandminutes

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/command/!hello/execution/count?minutes=60

GET/stats/{kickId}/command/execution/ranking

Command execution ranking

Returns the most-used commands for the selected time window.

Base URLAPI token

Kick IDminutestop

Requesthttps://kicklet.app/api/stats/%7BkickId%7D/command/execution/ranking?minutes=60&top=10

Variables and Counters

Variable endpoints use userId. Global variables have no viewer. Viewer variables include a viewer value. TTL is optional and uses seconds.

GET/{userId}/counter-variable

List counter variables

Returns all counter variables for the Kicklet account.

Base URLAPI token

Kicklet user ID

Requesthttps://kicklet.app/api/%7BuserId%7D/counter-variable

GET/{userId}/counter-variable/name/{name}

Get counter variable

Returns one counter variable by name.

Base URLAPI token

Kicklet user IDname

Requesthttps://kicklet.app/api/%7BuserId%7D/counter-variable/name/wins

PATCH/{userId}/counter-variable/name/{name}/set

Set counter variable

Replaces the counter value with an exact number.

Base URLAPI token

Kicklet user IDname

JSON body{ "value": 10 }

Requesthttps://kicklet.app/api/%7BuserId%7D/counter-variable/name/wins/set

PATCH/{userId}/counter-variable/name/{name}/increment

Increment counter variable

Adds the given value to the counter. Use a negative number to decrease it.

Base URLAPI token

Kicklet user IDname

JSON body{ "value": 1 }

Requesthttps://kicklet.app/api/%7BuserId%7D/counter-variable/name/wins/increment

GET/{userId}/variable

List global variables

Returns global variables, with pagination and search.

Base URLAPI token

Kicklet user IDpagepageSizesearch

Requesthttps://kicklet.app/api/%7BuserId%7D/variable?page=1&pageSize=100

GET/{userId}/variable/viewer/overview

List viewer variable names

Returns viewer-variable names and overview data.

Base URLAPI token

Kicklet user IDpagepageSizesearch

Requesthttps://kicklet.app/api/%7BuserId%7D/variable/viewer/overview?page=1&pageSize=100

GET/{userId}/variable/viewer/list/{variable}

List viewer variable values

Returns values for one viewer variable across viewers.

Base URLAPI token

Kicklet user IDvariablepagepageSizesearch

Requesthttps://kicklet.app/api/%7BuserId%7D/variable/viewer/list/rank?page=1&pageSize=100

PUT/{userId}/variable

Set variable

Creates or updates a global variable or viewer variable. Omit viewer for a global variable.

Base URLAPI token

Kicklet user ID

JSON body{ "variable": "promoCode", "viewer": null, "value": "KICKLET10", "TTL": null }

Requesthttps://kicklet.app/api/%7BuserId%7D/variable

DELETE/{userId}/variable

Delete variable

Deletes a global variable, one viewer variable value, or all viewer values for a variable.

Base URLAPI token

Kicklet user ID

JSON body{ "variable": "promoCode", "viewer": null, "allViewerVariables": false }

Requesthttps://kicklet.app/api/%7BuserId%7D/variable

Song Requests

Song endpoints use userId. Reading requires song.view; adding requires song.create; deleting, skipping, moving, and clearing require song.delete.

GET/song/{userId}

List song queue

Returns the song request queue.

Base URLAPI token

Kicklet user ID

Requesthttps://kicklet.app/api/song/%7BuserId%7D

GET/song/{userId}/current

Current song

Returns the currently playing song request.

Base URLAPI token

Kicklet user ID

Requesthttps://kicklet.app/api/song/%7BuserId%7D/current

POST/song/{userId}

Add song request

Adds a song request from a video URL or search term.

Base URLAPI token

Kicklet user ID

JSON body{ "videoSearch": "Never Gonna Give You Up" }

Requesthttps://kicklet.app/api/song/%7BuserId%7D

DELETE/song/{userId}/skip

Skip current song

Skips the currently playing song request.

Base URLAPI token

Kicklet user ID

Requesthttps://kicklet.app/api/song/%7BuserId%7D/skip

DELETE/song/{userId}/clear

Clear song queue

Removes all song requests from the queue.

Base URLAPI token

Kicklet user ID

Requesthttps://kicklet.app/api/song/%7BuserId%7D/clear

DELETE/song/{userId}/{songId}

Delete song request

Deletes one song request by ID.

Base URLAPI token

Kicklet user IDSong ID

Requesthttps://kicklet.app/api/song/%7BuserId%7D/%7BsongId%7D

Errors

Successful requests usually return JSON or 204 No Content. Invalid input returns 400 Bad Request, missing or invalid authentication returns 401 or 403, and permission failures return 403. When a backend operation fails, the gateway forwards the mapped error status and response from Kicklet.