# Kudos

> List and send kudos for team recognition — with pagination, search, and date range filtering.

Language: en
Canonical: https://www.dailybot.com/developers/api/kudos
Markdown: send header `Accept: text/markdown` on any URL to receive Markdown instead of HTML.
Last Updated: 2026-07-10

---

# Kudos

List, send, and manage kudos for team recognition.

## Endpoints summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/kudos/` | List kudos for the authenticated user |
| GET | `/v1/kudos/organization/` | List all kudos in the organization (admin only) |
| GET | `/v1/kudos/wall-of-fame/` | Top kudos contributors |
| POST | `/v1/kudos/` | Send kudos |
| POST | `/v1/kudos/{id}/boost/` | Boost a kudo |

---

## GET /v1/kudos/

Returns kudos for the authenticated user. Paginated (default ordering: `-id`).

### Query parameters

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-indexed). `offset` accepted as alias. |
| `page_size` | integer | 25 | Items per page (max 100). `limit` accepted as alias. |
| `type` | string | `kudos_received` | **Deprecated alias** — use `filter` instead. |
| `filter` | string | `kudos_received` | `kudos_received` or `kudos_given` (case-insensitive). Invalid values return `400 invalid_kudos_filter`. |
| `user_uuid` | string (UUID) | — | Filter by user. |
| `start_date` | string | — | Inclusive start date (`YYYY-MM-DD`, caller's timezone). Also accepted: `date_start`, `date_from`. |
| `end_date` | string | — | Inclusive end date (`YYYY-MM-DD`, caller's timezone). Also accepted: `date_end`, `date_to`. |
| `search` | string | — | Case-insensitive substring match on the kudos `message` field. Max 256 chars. Over-length returns `400 search_query_too_long`. |

> **Legacy aliases:** `date_start`/`date_end` and `limit`/`offset` continue to work and echo in `next`/`previous` URLs.

> **Validation errors:** Inverted date ranges (`start_date > end_date`) or malformed dates return `400 invalid_date_range`.

```bash
curl "https://api.dailybot.com/v1/kudos/?type=kudos_received&start_date=2026-07-01&end_date=2026-07-31&page_size=50" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"
```

**Response (200 OK):**

```json
{
  "count": 15,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "kudos-uuid",
      "from_user": { "uuid": "usr_001", "name": "Alice" },
      "to_user": { "uuid": "usr_002", "name": "Bob" },
      "message": "Great work on the release!",
      "points": 1,
      "created_at": "2026-07-05T14:00:00Z"
    }
  ]
}
```

---

## GET /v1/kudos/organization/

Returns all **top-level** kudos across the entire organization. Requires organization admin role. Always paginated (standard envelope). Ordered by `created_at DESC` with `id` as a deterministic tiebreaker.

**Authentication:** Accepts both `X-API-KEY` (organization API key) and `Authorization: Bearer <token>` (CLI Bearer token or session token). The admin permission requirement applies to whichever credential is used — non-admins receive `403` with `code: "org_admin_required"`.

### Query parameters

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-based). |
| `page_size` | integer | 25 | Items per page (max 100). `limit` accepted as alias. |
| `filter` | string | — | `kudos_received` or `kudos_given` (case-insensitive). Invalid values return `400 invalid_kudos_filter`. |
| `search` | string | — | Case-insensitive substring match on kudos content. Max 256 chars. Over-length returns `400 search_query_too_long`. |
| `start_date` | string (`YYYY-MM-DD`) | — | Timezone-aware inclusive start (caller's timezone). Preferred over the legacy `date_start`. |
| `end_date` | string (`YYYY-MM-DD`) | — | Timezone-aware inclusive end (`23:59:59` in caller's timezone). Preferred over the legacy `date_end`. |
| `date_start` | string (`YYYY-MM-DD`) | — | Legacy naive-day start filter (still available). Stacks with `start_date` if both are provided. |
| `date_end` | string (`YYYY-MM-DD`) | — | Legacy naive-day end filter (still available). Stacks with `end_date` if both are provided. |
| `sender_uuid` | string (UUID) | — | Filter by the user who sent the kudo. Must be a valid UUID v4 or the API returns `400 invalid_sender_uuid`. |
| `receiver_uuid` | string (UUID) | — | Filter by the user who received the kudo. Must be a valid UUID v4 or the API returns `400 invalid_receiver_uuid`. |

> **Date filter guidance:** Prefer `start_date` / `end_date` for new integrations — they respect the authenticated user's timezone. `date_start` / `date_end` remain available as the naive-day legacy filter and can be combined with the timezone-aware pair (filters stack). If `start_date` is after `end_date`, the API returns `400 invalid_date_range`.

### Examples

```bash
# List all organization kudos (default pagination)
curl -sS "https://api.dailybot.com/v1/kudos/organization/" \
  -H "Authorization: Bearer $DAILYBOT_CLI_TOKEN"

# Filter by date range (timezone-aware)
curl -sS "https://api.dailybot.com/v1/kudos/organization/?start_date=2026-06-01&end_date=2026-06-30" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

# Filter by sender
curl -sS "https://api.dailybot.com/v1/kudos/organization/?sender_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer $DAILYBOT_CLI_TOKEN"

# Filter by receiver with pagination
curl -sS "https://api.dailybot.com/v1/kudos/organization/?receiver_uuid=7c9e6679-7425-40de-944b-e07fc1f90ae7&page=2&page_size=10" \
  -H "Authorization: Bearer $DAILYBOT_CLI_TOKEN"

# Filter by type (only kudos received across the org)
curl -sS "https://api.dailybot.com/v1/kudos/organization/?filter=kudos_received" \
  -H "Authorization: Bearer $DAILYBOT_CLI_TOKEN"
```

### Response (200 OK)

```json
{
  "count": 156,
  "next": "https://api.dailybot.com/v1/kudos/organization/?page=2",
  "previous": null,
  "results": [
    {
      "id": "a8283c36-8e5f-40cb-92ca-9e483eb6bde2",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "full_name": "Jane Smith",
        "image": "https://avatars.slack-edge.com/..."
      },
      "receivers": [
        {
          "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "full_name": "John Doe",
          "image": "https://avatars.slack-edge.com/..."
        }
      ],
      "company_value": {
        "id": "d4735e3a-265e-16d7-3dca-60b8831c8295",
        "value": "Teamwork",
        "description": "Collaboration and support",
        "emoji": "🤝",
        "i18n_meta": {}
      },
      "content": "Thanks for the incredible help with the product launch!",
      "is_anonymous": false,
      "created_at": "2026-07-08T14:30:00.123456Z"
    }
  ]
}
```

#### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `count` | integer | Total kudos matching the query (across all pages). |
| `next` | string \| null | URL to the next page, or `null` on the last page. |
| `previous` | string \| null | URL to the previous page, or `null` on the first page. |
| `results` | array | Kudo objects for the current page. |

#### Kudo object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string (UUID) | Unique identifier for the kudo. |
| `user` | object | Sender: `{ uuid, full_name, image }`. When `is_anonymous` is `true`, this is anonymized (random display name, no real identity). |
| `receivers` | array | Recipients: `[{ uuid, full_name, image }]`. |
| `company_value` | object \| null | Attached company value: `{ id, value, description, emoji, i18n_meta }`. `null` when no value is attached. |
| `content` | string | The kudo message (HTML-sanitized). |
| `is_anonymous` | boolean | Whether the kudo was sent anonymously. |
| `created_at` | string (ISO 8601) | Creation timestamp. |

### Error responses

**`400 invalid_date_range`** — `start_date > end_date` or a malformed date.

```json
{
  "detail": "Invalid 'start_date' value. Expected YYYY-MM-DD.",
  "code": "invalid_date_range"
}
```

**`400 invalid_kudos_filter`** — `filter` is not one of the accepted values (case-insensitive).

```json
{
  "detail": "Not valid kudos filter. Accepted values: kudos_received, kudos_given.",
  "code": "invalid_kudos_filter"
}
```

**`403 org_admin_required`** — caller is not an organization admin.

```json
{
  "detail": "This endpoint requires organization admin privileges.",
  "code": "org_admin_required"
}
```

**`400 invalid_sender_uuid`** — `sender_uuid` is not a valid UUID.

```json
{
  "detail": "Invalid UUID format for 'sender_uuid'.",
  "code": "invalid_sender_uuid"
}
```

**`400 invalid_receiver_uuid`** — `receiver_uuid` is not a valid UUID.

```json
{
  "detail": "Invalid UUID format for 'receiver_uuid'.",
  "code": "invalid_receiver_uuid"
}
```

**`401 Unauthorized`** — Missing or invalid credential.

**`403 Forbidden`** — Authenticated user is not an organization admin.

### Notes

- Only **top-level kudos** are returned — replies are excluded (`parent__isnull=True`).
- If the organization has anonymous kudos disabled (`allow_anonymous_messages = false`), anonymous kudos are excluded from results.
- `limit` / `offset` are accepted as backward-compatible aliases for page-size and offset-based pagination.

---

## GET /v1/kudos/wall-of-fame/

Returns top kudos contributors in the organization. Paginated (default ordering: `-count`).

Accepts the same `page`, `page_size`, `start_date`, and `end_date` parameters.

---

## POST /v1/kudos/

Sends kudos to a team member.

### Body parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `receivers` | array of strings | Conditional | User identifiers (UUIDs, emails, or external IDs). Required if `users_receivers` and `teams_receivers` are not provided. |
| `users_receivers` | array of UUIDs | Conditional | Explicit user UUIDs to receive the kudo. |
| `teams_receivers` | array of UUIDs | No | Team UUIDs. All active members receive the kudo. |
| `content` | string | No | Kudo message text (HTML-safe). |
| `is_anonymous` | boolean | No | When true, the sender is anonymized. Default: false. |
| `company_value` | string (UUID) | No | Company value ID to attach (if organization uses values). |

```bash
curl -X POST "https://api.dailybot.com/v1/kudos/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receivers": ["usr_002"],
    "content": "Excellent work on the API redesign!",
    "company_value": "value-uuid"
  }'
```

**Response (201 Created):**

```json
{
  "id": "kudos-uuid",
  "user": { "uuid": "usr_001", "full_name": "Alice" },
  "receivers": [{ "uuid": "usr_002", "full_name": "Bob" }],
  "content": "Excellent work on the API redesign!",
  "company_value": { "id": "value-uuid", "name": "Teamwork" },
  "is_anonymous": false,
  "by_dailybot": false,
  "created_at": "2026-07-09T10:00:00Z"
}
```

---

## POST /v1/kudos/{id}/boost/

Boosts an existing kudo by adding your endorsement.

```bash
curl -X POST "https://api.dailybot.com/v1/kudos/kudos-uuid/boost/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"
```

**Response (200 OK):**

```json
{
  "id": "kudos-uuid",
  "boosts": 1,
  "boosted_by": [{ "uuid": "usr_003", "name": "Carol" }]
}
```

## Endpoints in this group

Give and read kudos, including organization-wide stats and the wall-of-fame leaderboard. The `by_dailybot` field is stripped for CLI-token callers.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/kudos/` | List kudos |
| POST | `/v1/kudos/` | Give kudos |
| GET | `/v1/kudos/organization/` | List all kudos in the organization (admin only) |
| GET | `/v1/kudos/wall-of-fame/` | Wall of fame leaderboard |

### GET `/v1/kudos/`

**List kudos**

Paginated list of kudos the caller can access. Returns the standard envelope ({count, next, previous, results}). Supports sender/receiver filters, date range, and message search.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** Page-number pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filter` | string | No | Filter type: kudos_received or kudos_given (case-insensitive). Invalid values return 400 invalid_kudos_filter. |
| `sender_uuid` | string (uuid) | No | Filter to kudos sent by a specific user. |
| `receiver_uuid` | string (uuid) | No | Filter to kudos received by a specific user. |
| `start_date` | string (YYYY-MM-DD) | No | Inclusive start date (caller's timezone). Also accepted: date_start, date_from. |
| `end_date` | string (YYYY-MM-DD) | No | Inclusive end date, 23:59:59 in caller's timezone. Also accepted: date_end, date_to. |
| `search` | string | No | Case-insensitive substring search on the kudos message. Max 256 chars. |
| `page` | integer | No | Page number (1-indexed). Default: 1. |
| `page_size` | integer | No | Items per page. Default: 50, max: 200. Alias: limit. |

#### Response body

```json
{
  "count": "integer",
  "next": "string|null",
  "previous": "string|null",
  "results": "array<{ id, sender, receiver, message, created_at, ... }>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | Validation error (invalid_kudos_filter, search_query_too_long, invalid_date_range) |
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/kudos/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/kudos/`

**Give kudos**

Body: receivers (array), message; optional kudo_type_uuid, is_public, team_uuid, by_dailybot. Note: by_dailybot is stripped when the caller uses a CLI token.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/kudos/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

#### Notes

- by_dailybot is stripped for CLI tokens.

### GET `/v1/kudos/organization/`

**List all kudos in the organization (admin only)**

Returns all top-level kudos across the entire organization. Requires organization admin role. Accepts either an organization API key (X-API-KEY) or a CLI Bearer token (Authorization: Bearer <token>). Supports sender/receiver filters, both legacy naive and timezone-aware date ranges, and a filter type (kudos_received / kudos_given). Only top-level kudos are returned (replies excluded).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** Page-number pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filter` | string | No | Filter type: 'kudos_received' or 'kudos_given' (case-insensitive). Invalid values return 400 invalid_kudos_filter. |
| `sender_uuid` | string (uuid) | No | Filter by sender (user who gave the kudo). Must be a valid UUID v4 or the request returns 400 invalid_sender_uuid. |
| `receiver_uuid` | string (uuid) | No | Filter by receiver (user who received the kudo). Must be a valid UUID v4 or the request returns 400 invalid_receiver_uuid. |
| `start_date` | string (YYYY-MM-DD) | No | Timezone-aware inclusive start date (caller's timezone). Preferred over the legacy date_start. |
| `end_date` | string (YYYY-MM-DD) | No | Timezone-aware inclusive end date, 23:59:59 in caller's timezone. Preferred over the legacy date_end. |
| `date_start` | string (YYYY-MM-DD) | No | Legacy naive-day start filter (always available). Stacks with start_date if both are provided. |
| `date_end` | string (YYYY-MM-DD) | No | Legacy naive-day end filter (always available). Stacks with end_date if both are provided. |
| `search` | string | No | Case-insensitive substring match on kudos content. Max 256 chars. |
| `page` | integer | No | Page number (1-indexed). Default: 1. |
| `page_size` | integer | No | Items per page. Default: 25, max: 100. Alias: limit. |
| `offset` | integer | No | Offset-based pagination (accepted for backward compatibility). |

#### Response body

```json
{
  "count": "integer",
  "next": "string|null",
  "previous": "string|null",
  "results": "array<{ id, user: { uuid, full_name, image }, receivers: array<{ uuid, full_name, image }>, company_value: { id, value, description, emoji, i18n_meta } | null, content, is_anonymous, created_at }>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | Validation error (invalid_date_range, invalid_kudos_filter, invalid_sender_uuid, invalid_receiver_uuid, search_query_too_long) |
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not an organization admin (`org_admin_required`) |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/kudos/organization/?start_date=2026-06-01&end_date=2026-06-30' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

#### Notes

- Only top-level kudos are returned (replies excluded via parent__isnull=True).
- If the organization has anonymous kudos disabled (allow_anonymous_messages=false), anonymous kudos are excluded from results.
- Ordered by created_at DESC with id as tiebreaker for deterministic pagination.

### GET `/v1/kudos/wall-of-fame/`

**Wall of fame leaderboard**

Wall of fame leaderboard

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** Page-number pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | enum (week,month,quarter,year,all_time) | No | Default: month. |
| `team_uuid` | string (uuid) | No | — |
| `page` | integer | No | Page number (1-indexed). Default: 1. |
| `page_size` | integer | No | Items per page. Default: 50, max: 200. Alias: limit. |

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/kudos/wall-of-fame/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

---

## Developer portal navigation

**Getting Started**

- [Overview](/developers)
- [Quick start](/developers/getting-started)
- [Authentication](/developers/authentication)

**API Reference**

- [API Overview](/developers/api)
- [Users](/developers/api/users)
- [Organization](/developers/api/organization)
- [Teams](/developers/api/teams)
- [Invitations](/developers/api/invitations)
- [Check-ins](/developers/api/check-ins)
- [Forms](/developers/api/forms)
- [Report channels](/developers/api/report-channels)
- [Templates](/developers/api/templates)
- [Kudos](/developers/api/kudos) (this page)
- [Mood tracking](/developers/api/mood)
- [Important dates](/developers/api/important-dates)
- [Messaging](/developers/api/messaging)
- [Automations](/developers/api/workflows)
- [Webhooks](/developers/api/webhooks)
- [Commands platform](/developers/api/commands-platform)
- [Agents](/developers/api/agents)
- [OAuth2](/developers/api/oauth2)
- [Integrations](/developers/api/integrations)
- [CLI](/developers/api/cli)

**API guides**

- [Errors & Status Codes](/developers/errors)
- [Rate Limits](/developers/rate-limits)
- [Conventions](/developers/conventions)
- [API Changelog](/developers/api-changelog)
- [Recipes](/developers/recipes)

**Developer Features**

- [Custom commands](/developers/custom-commands)
- [Serverless commands](/developers/serverless)
- [Webhooks & events](/developers/webhooks)
- [Automation API trigger](/developers/workflow-trigger)
- [Activity API](/developers/activity-api)

**CLI**

- [Overview](/developers/cli)
- [Authentication](/developers/cli-authentication)
- [Command reference](/developers/cli-reference)
- [CI/CD recipes](/developers/cli-ci-cd)
- [Configuration](/developers/cli-configuration)
- [Troubleshooting](/developers/cli-troubleshooting)

**Agent Skill**

- [Overview](/developers/agent-skill)
- [Skills catalog](/skills)

---

## Site navigation

**Product:**
- [Home](/)
- [Product](/product)
- [Pricing](/pricing)
- [Enterprise](/enterprise)
- [Integrations](/integrations)
- [Templates](/templates)

**Resources:**
- [Blog](/blog)
- [Academy](/academy)
- [Changelog](/changelog)
- [Help Center](/help)
- [Developers](/developers)
- [Agents](/agents)

**Company:**
- [About](/about)
- [Careers](/careers)
- [Security](/security)
- [Contact Sales](/demo)

**Connect:**
- [LinkedIn](https://www.linkedin.com/company/dailybot/)
- [X/Twitter](https://twitter.com/dailybot)
- [GitHub](https://github.com/Dailybot-Inc)
- [YouTube](https://www.youtube.com/channel/UC3uM9V52vwX7e3vQpCc4qvA)