Quickstart with the REST API

This page takes you from an API key to a working command and timed message in four calls. It uses curl, but any HTTP client works. All endpoints are under https://kickbot.com/api/v1.

First, create an API key with Read and write access. Then put it in an environment variable:

export KICKBOT_API_KEY="kb_live_..."

1. Read the account overview

curl https://kickbot.com/api/v1/account \
  -H "Authorization: Bearer $KICKBOT_API_KEY"

The response shows your channel, its plan and limits, your permissions, and the areas you can use. A shortened example:

{
  "data": {
    "channel": { "id": 123, "kick_username": "yourchannel", "plan": "premium", "kickbot_is_moderator": true },
    "limits": { "enabled_custom_commands": null, "timed_messages": null },
    "areas": [{ "area": "commands", "title": "Custom commands", "available": true }]
  }
}

A limit of null means there is no plan limit. On the Free plan the limits are numbers, for example "enabled_custom_commands": 5 and "timed_messages": 3.

2. Create a command

curl -X POST https://kickbot.com/api/v1/commands \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "discord", "response": "Join the Discord: https://discord.gg/your-server-code"}'

A create returns HTTP 201. Viewers can now type !discord in your chat.

To run the same setup more than one time without making duplicates, use the command name in the path. This creates the command, or changes it if it already exists:

curl -X PUT https://kickbot.com/api/v1/commands/by-name/discord \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"response": "Join the Discord: https://discord.gg/your-server-code"}'

3. Add a timed message

curl -X POST https://kickbot.com/api/v1/timers \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Follow the channel so you do not miss a stream!", "interval": 30, "spacing": 5}'

interval is the number of minutes between posts. spacing is how many viewer messages must come between two posts, so KickBot does not post into an empty chat.

4. Change only some fields

Update actions change only the fields you send. For example, to turn off command 42:

curl -X PATCH https://kickbot.com/api/v1/commands/42 \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Get the command id from GET /api/v1/commands.

Response format

• Success: { "data": ... }. A create returns HTTP 201. Other successful calls return HTTP 200.
• Error: { "error": { "code", "message", "fields", "request_id" } }. See Errors and limits.
• GET and DELETE take their fields in the query string. Other methods take a JSON body.

Every endpoint and its fields are in the API reference, for example Custom commands and Timed messages. The same information is in the OpenAPI file.