# Quickstart with the REST API

> Make your first KickBot API calls with curl, from reading your account overview to creating a command and a timed message on your Kick channel.

Source: https://kickbot.com/docs/api/start/quickstart

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](https://kickbot.com/docs/api/start/api-keys) with **Read and write** access. Then put it in an environment variable:

```bash
export KICKBOT_API_KEY="kb_live_..."
```

## 1. Read the account overview

```bash
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:

```json
{
  "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

```bash
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:

```bash
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

```bash
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:

```bash
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](https://kickbot.com/docs/api/start/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](https://kickbot.com/docs/api/reference/commands) and [Timed messages](https://kickbot.com/docs/api/reference/timers). The same information is in the [OpenAPI file](https://kickbot.com/api/v1/openapi.json).