> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.karmabot.chat/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# API Webhook

Karma bot supports an external API that allows you to assign karma and retrieve workspace data via HTTP requests from your services.

> We recommend using [Postman](https://www.postman.com/) or any REST client for testing.

## Step 1: Create an API Key

Go to **Dashboard → API keys** (`/admin/options/api`).

The page shows a list of all created keys with their creation date and author. Click `Create API Key`, enter a name for the key and it will be generated.

> The API key is shown **only once** immediately after creation. Save it, you won't be able to view the key value again.

The key has the following format:

```
krm_{id}_{token}
```


![](https://storage.crisp.chat/users/helpdesk/website/-/2/4/3/e/243e916e9fc1a000/cleanshot-2026-04-14-at-141241_b6bxa1.png)

## Step 2: Authentication

All API requests require passing the key in the `Authorization` header:

```
Authorization: Bearer krm_{id}_{token}
```

## Base URL

The base URL for all API requests is:

```
https://app.karmabot.chat/api/v1
```

## Endpoints

Full documentation is available directly in the app at `/admin/options/api/documentation`.

![](https://storage.crisp.chat/users/helpdesk/website/-/2/4/3/e/243e916e9fc1a000/cleanshot-2026-04-14-at-141459_138atj1.png)


---

### GET /channels

Returns a paginated list of workspace channels available for karma requests.

**Parameters**

| Parameter | Description |
| ---- |
| `cursor` | Pagination cursor (ID of the last received item) |

**Request example:**

```
GET /channels?cursor=4836286113
Authorization: Bearer krm_{id}_{token}
```

**Response example:**

```json
{
    "channels": [
        {
            "id": 4836286113,
            "slack_id": "C077X9W7LHY",
            "name": "Channel#1",
            "is_private": false
        },
        {
            "id": 4836286122,
            "slack_id": "C084BVD05A5",
            "name": "Channel#2",
            "is_private": false
        }
    ]
}
```

---

### GET /users

Returns a paginated list of workspace members available as senders or recipients of karma requests.

**Parameters**

| Parameter | Description |
| ---- |
| `cursor` | Pagination cursor |

**Request example:**

```
GET /users?cursor=18152430041
Authorization: Bearer krm_{id}_{token}
```

**Response example:**

```json
{
    "users": [
        {
            "id": 18152430041,
            "slack_id": "U051U28Q3RV",
            "name": "User 1",
            "image_url": "https://...png"
        },
        {
            "id": 18152430072,
            "slack_id": "U051U2EMMP1",
            "name": "User 2",
            "image_url": "https://...png"
        }
    ]
}
```

---

### GET /values

Returns a paginated list of company values that can be attached to a karma request.

**Parameters**

| Parameter | Description |
| ---- |
| `cursor` | Pagination cursor |

**Request example:**

```
GET /values?cursor=47140
Authorization: Bearer krm_{id}_{token}
```

**Response example:**

```json
{
    "values": [
        {
            "id": 47141,
            "color": "#4C94FF",
            "description": "description.",
            "emoji": ":gem:",
            "image_url": "https://...png",
            "name": "Reliability"
        }
    ]
}
```

---

### GET /achievements

Returns a paginated list of achievements that can be granted to users alongside a karma request.

**Parameters**

| Parameter | Description |
| ---- |
| `cursor` | Pagination cursor |

**Request example:**

```
GET /achievements?cursor=19475
Authorization: Bearer krm_{id}_{token}
```

**Response example:**

```json
{
    "achievements": [
        {
            "id": 19476,
            "title": "Happy Birthday!",
            "emoji": "tada",
            "color": "#92d279",
            "description": null,
            "value_id": null
        }
    ]
}
```

---

### POST /pluses

Creates a karma request from one user to one or more recipients. Optionally attach a value, achievement, gif, and control visibility.

> **Rate limit:** 6 requests per minute per team.

**Parameters**

| Parameter | Type | Required | Description |
| ---- |
| `user_ids` | Array[Integer] | ✓ | Array of recipient IDs |
| `from_id` | Integer | ✓ | Sender ID |
| `description` | String | ✓ | Karma request message / reason |
| `channel_id` | Integer | ✓ | ID of the channel where the request will be posted |
| `score` | Integer | ✓ | Number of karma points |
| `private` | Boolean | ✓ | Visibility (`false` — public, `true` — private) |
| `value_id` | Integer | — | Company value ID |
| `achievement_id` | Integer | — | Achievement ID |
| `gif_url` | String | — | GIF attachment URL |

**Request example:**

```
POST /pluses
Authorization: Bearer krm_{id}_{token}
Content-Type: application/json

{
    "description": "Great work on the release!",
    "user_ids": [1815243014, 1815243015],
    "from_id": 1815243016,
    "channel_id": 483628611,
    "score": 1,
    "private": false,
    "value_id": 47142
}
```

**Response:** `201 Created`

---

## Rate Limits

| Endpoint | Limit |
| ---- |
| GET /channels | 120 req/min |
| GET /users | 120 req/min |
| GET /values | 120 req/min |
| GET /achievements | 120 req/min |
| POST /pluses | 6 req/min |

Limits are applied per team.

---

## Managing API Keys

On the `/admin/options/api` page you can:

* **Rename** a key via the `⋯` menu next to the key. 
* **Delete** a key — after deletion, all requests using that key will stop working.