> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teambuilder.ge/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every TeamBuilder API endpoint, generated from the OpenAPI specification, with a live playground.

## Base URL

```text theme={null}
https://api.teambuilder.ge
```

Every path starts with `/v1`. All traffic is HTTPS.

## Authentication

Send your key as a Bearer token on every request:

```text theme={null}
Authorization: Bearer tb_live_...
```

Each endpoint page lists the scope it needs. See [Authentication](/authentication).

## Conventions

| Topic | Convention |
| - | - |
| Format | JSON request and response bodies, `snake_case` keys, UTF-8 |
| Timestamps | ISO 8601 in UTC, for example `2026-10-20T09:30:00.000Z` |
| Identifiers | TeamBuilder ids are UUIDs. `external_id` fields hold your HR system's keys. |
| Lists | `{"data": [...], "pagination": {"next_cursor": ...}}`. See [Pagination](/reference/pagination). |
| Errors | `{"error": {"code", "message", "request_id"}}`. See [Errors](/reference/errors). |
| Rate limits | 60 requests per minute per key, reported in `X-RateLimit-*` headers. See [Rate limits](/reference/rate-limits). |
| Tracing | Every response carries an `X-Request-Id` header. Quote it when you contact support. |
| Nullable fields | Documented fields are always present; a field without a value is `null`, never omitted. |

## Endpoints

| Method | Path | Scope |
| - | - | - |
| `GET` | [`/v1/ping`](/api-reference/status/check-your-api-key) | any key |
| `GET` | [`/v1/employees`](/api-reference/employees/list-employees) | `employees:read` |
| `GET` | [`/v1/employees/{id}`](/api-reference/employees/retrieve-an-employee) | `employees:read` |
| `GET` | [`/v1/employees/{id}/stats`](/api-reference/employees/retrieve-employee-stats) | `employees:read` |
| `GET` | [`/v1/employees/{id}/badges`](/api-reference/employees/list-employee-badges) | `employees:read` |
| `PUT` | [`/v1/employees/sync`](/api-reference/roster-sync/sync-your-employee-roster) | `employees:write` |
| `GET` | [`/v1/leaderboard`](/api-reference/leaderboard/get-the-leaderboard) | `leaderboard:read` |
| `GET` | [`/v1/leaderboard/by-department`](/api-reference/leaderboard/get-the-leaderboard-by-department) | `leaderboard:read` |
| `GET` | [`/v1/departments`](/api-reference/departments/list-departments) | `departments:read` |
| `GET` | [`/v1/shop/items`](/api-reference/shop/list-shop-items) | `shop:read` |

## Using the playground

Each endpoint page has a **Try it** playground. Paste a key into the authorisation field and send real requests.

<Warning>
  Playground requests are relayed through Mintlify's servers, which host this documentation, so the key you paste leaves your machine. Use a `tb_test_` key in the playground, never a live key.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.