> ## 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.

# Introduction

> Bring TeamBuilder levels, XP leaderboards and rewards into your intranet, and keep your employee roster in sync from your HR system.

The TeamBuilder API gives your internal systems read access to your company's gamification data and one write operation: syncing your roster. It is a server-to-server REST API with JSON responses, Bearer-key authentication and cursor pagination.

**Who it's for:** engineering and IT teams at companies that use TeamBuilder and want its data where employees already spend their day: an intranet, an internal portal, Slack or Teams bots, office screens, or a data warehouse.

## What you can build

<CardGroup cols={1}>
  <Card title="Leaderboards" icon="trophy" href="/guides/leaderboards" horizontal>
    Rank people by XP for this month, the last 3 months, the last year or all time, company-wide or per department.
  </Card>

  <Card title="Employee widgets" icon="id-badge" href="/guides/employee-widgets" horizontal>
    Show level, XP progress, coins, ranks and badges on intranet profiles, plus your reward catalogue.
  </Card>

  <Card title="Roster sync" icon="arrows-rotate" href="/guides/roster-sync" horizontal>
    Push your HR roster daily so joiners, departments, job titles and leavers stay current automatically.
  </Card>
</CardGroup>

## Base URL

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

All requests use HTTPS. Request and response bodies are JSON with `snake_case` keys, and timestamps are ISO 8601 in UTC.

## A 20-second example

Fetch this month's top employee:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.teambuilder.ge/v1/leaderboard?period=this_month&limit=1" \
    -H "Authorization: Bearer $TEAMBUILDER_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://api.teambuilder.ge/v1/leaderboard?period=this_month&limit=1",
    { headers: { Authorization: `Bearer ${process.env.TEAMBUILDER_API_KEY}` } },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      "https://api.teambuilder.ge/v1/leaderboard",
      params={"period": "this_month", "limit": 1},
      headers={"Authorization": f"Bearer {os.environ['TEAMBUILDER_API_KEY']}"},
      timeout=10,
  )
  data = res.json()["data"]
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "rank": 1,
      "employee_id": "3f1c2a9e-8d4b-4c61-9a57-0e2b6f7d1a43",
      "external_id": "EMP-00042",
      "name": "Nino Beridze",
      "department": {
        "id": "b7e0c4d2-1f3a-4e8b-9c6d-2a5f8e1b7c90",
        "external_id": "D-ENG",
        "name": "Engineering"
      },
      "level": 12,
      "xp": 2300
    }
  ],
  "pagination": { "next_cursor": "djEuQ2lwaGVydGV4dEV4YW1wbGU" }
}
```

Leaderboards rank people by XP, never by coins. Coin balances are available per employee from the [employee stats](/api-reference/employees/retrieve-employee-stats) endpoint.

## Principles

<AccordionGroup>
  <Accordion title="Your data, scoped by your key" icon="lock">
    Every key belongs to exactly one company, and the company is resolved from the key alone, never from a parameter. Deactivated employees never appear in any response.
  </Accordion>

  <Accordion title="Predictable shapes" icon="brackets-curly">
    Lists return `{"data": [], "pagination": {"next_cursor"}}`. Errors return `{"error": {"code", "message", "request_id"}}`. Every response carries an `X-Request-Id` header.
  </Accordion>

  <Accordion title="A sandbox for every customer" icon="flask">
    `tb_test_` keys read a sandbox company seeded with realistic sample data, through the same endpoints and response shapes as live keys.
  </Accordion>

  <Accordion title="Stable v1" icon="code-branch">
    Changes within `/v1` are additive. Breaking changes ship as a new version, and a deprecated version keeps working for at least six months after the announcement. See [Versioning](/reference/versioning).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart" horizontal>
    Your first request in five minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication" horizontal>
    Keys, scopes and rotation.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction" horizontal>
    Every endpoint, with a live playground.
  </Card>

  <Card title="Get API access" icon="envelope" href="mailto:contact@teambuilder.ge" horizontal>
    Ask for live and test keys for your company.
  </Card>
</CardGroup>


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