> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/using-hivel/hivel-public-api/teams.md).

# Teams

#### Why Use This?

The Public Teams API lets you programmatically retrieve your organization's team structure and metadata without going through the Hivel UI. Use it to sync team data into another system, build custom integrations or dashboards, or look up teams by name from an external tool.

#### What Data Can Be Retrieved?

Through this endpoint, you can retrieve:

* **All teams in your organization**, in a single call.
* **A specific team by name**, using a search param (mentioned in detail below).
* **Team hierarchy**, seeing which teams are nested under which parent team.

### Step 1: Generate an API Token

1. Log in to Hivel as an organization admin.
2. Go to **Settings → API Token Management**.<br>

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FRHkU3KbffS2vbr4HTzBF%2FScreenshot%202026-08-31%20at%2011.52.46%E2%80%AFPM.png?alt=media&amp;token=3e91b79b-da21-4c0c-97fd-e79952f22157" alt=""><figcaption></figcaption></figure>
3. Click **Generate Token**.
4. Give the token a name and click **Generate**.
5. Copy the generated token immediately - it follows the format:

   ```
   HIVEL_PUBLIC_API_<organizationId>_<uuid>
   ```

   \
   For example: <mark style="color:$warning;">`HIVEL_PUBLIC_API_2116_a1b2c3d4-e5f6-7890-abcd-ef1234567890`</mark><br>

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FjvJEMw0dwlpta6p9Lghe%2FUntitled%20design%20(4).png?alt=media&amp;token=26276327-c0c9-4556-a921-8d6331ba12af" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Note:** Only **one active key per organization** is allowed at a time - generating a new one invalidates the previous key. Store it securely; it will not be shown again after this step.
{% endhint %}

### Step 2: Authenticate Requests

You can call the API using any of the following:

* A terminal, using **curl**
* A GUI tool such as Postman.
* Your own application's code, in any programming language

Every request to the Teams API must include this token as a Bearer token in the `Authorization` header:

```
Authorization: Bearer HIVEL_PUBLIC_API_<organizationId>_<uuid>
```

No other headers (such as `X-Organization-Id` or `X-User-Id`) are required - your organization is resolved automatically from the token itself.

### Step 3: Fetch Teams Data

**BaseURL:**

{% code expandable="true" %}

```
https://app.hivel.ai
```

{% endcode %}

\
**Endpoint:**

```
GET /hivelapi/public/v1/teams
```

{% hint style="info" %}
This single endpoint covers three use cases - retrieving all teams, searching teams, and viewing them in a hierarchical structure - controlled entirely by query parameters.
{% endhint %}

**Query Parameters**

<table><thead><tr><th width="139.41015625">Param</th><th width="91.3515625">Type</th><th width="95.375">Required</th><th width="99.27734375">Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>search_term</code></td><td>string</td><td>No</td><td>-</td><td>Filters teams by name, using a case-insensitive substring match. Max 100 characters. When set, the response is <strong>always flat</strong>, regardless of <code>flat</code>.</td></tr><tr><td><code>flat</code></td><td>boolean</td><td>No</td><td><code>true</code></td><td>Controls the response structure: a flat list (default) or a nested tree. Set to <code>false</code> for hierarchical mode. Ignored (forced <code>true</code>) when <code>search_term</code> is set.</td></tr><tr><td><code>offset</code></td><td>int</td><td>No</td><td><code>0</code></td><td>Number of records to skip, for pagination. Applies only in flat mode - ignored in hierarchical mode.</td></tr><tr><td><code>page_size</code></td><td>int</td><td>No</td><td><code>50</code></td><td>Number of records to return per page, range 1-50. Appl</td></tr></tbody></table>

**Response Shape**

```
{ "total": <number>, "items": [ ...team objects... ] }
```

* Every response also includes rate-limit information via the <mark style="color:blue;">`RateLimit-Limit`</mark>, <mark style="color:blue;">`RateLimit-Remaining`</mark>, and <mark style="color:blue;">`RateLimit-Reset`</mark> headers.

`total` respects `search_term` filtering in flat mode; in hierarchical mode, it reflects the total team count in the organization, not just the root-level count.

**Response Object Fields**

<table data-search="false"><thead><tr><th width="174.34375">Field</th><th width="189.390625">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>id</code></td><td>int</td><td>Unique identifier for the team.</td></tr><tr><td><code>name</code></td><td>string</td><td>The team's display name.</td></tr><tr><td><code>organizationId</code></td><td>int</td><td>ID of the organization the team belongs to.</td></tr><tr><td><code>teamType</code></td><td>string | null</td><td>Raw value - no fixed enum.</td></tr><tr><td><code>parentTeamId</code></td><td>int | null</td><td>ID of the parent team. <code>null</code> indicates a top -level team.</td></tr><tr><td><code>ownerName</code></td><td>string | null</td><td>Display name of the team's owner. <code>null</code> if no owner is set.</td></tr><tr><td><code>createdAt</code></td><td>ISO datetime | null</td><td>Timestamp when the team was created. <code>null</code> if unavailable.</td></tr><tr><td><code>state</code></td><td>string</td><td><code>"ACTIVE"</code> or <code>"DELETED"</code>.</td></tr><tr><td><code>subTeamCount</code></td><td>int</td><td>Number of direct child teams. Only present when <mark style="color:$warning;"><code>flat=false</code></mark>.</td></tr><tr><td><code>subTeams</code></td><td>array</td><td>Empty in flat mode; contains nested child team objects in hierarchical mode. Only present when <mark style="color:$warning;"><code>flat=false</code></mark>.</td></tr></tbody></table>

### **Use Cases**&#x20;

1. **Retrieve all teams (flat, default)**

**Request:**&#x20;

```
curl -s "https://app.hivel.ai/hivelapi/public/v1/teams" \
  -H "Authorization: Bearer <HIVEL_PUBLIC_API_TOKEN>"
```

**example:**

```
curl -s "https://app.hivel.ai/hivelapi/public/v1/teams" \
  -H "Authorization: Bearer HIVEL_PUBLIC_API_2116_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

**Response:**

{% code expandable="true" %}

```
{
  "total": 2,
  "items": [
    {
      "id": 101,
      "name": "Platform",
      "organizationId": 2116,
      "teamType": "PUBLIC",
      "parentTeamId": null,
      "ownerName": "Jane Doe",
      "createdAt": "2025-01-10T09:00:00",
      "state": "ACTIVE"
    },
    {
      "id": 102,
      "name": "Platform - Infra",
      "organizationId": 2116,
      "teamType": "PUBLIC",
      "parentTeamId": 101,
      "ownerName": "John Smith",
      "createdAt": "2025-02-03T11:30:00",
      "state": "ACTIVE"
    }
  ]
}
```

{% endcode %}

2. **Search teams by name**

**Request:**

<pre><code><strong>curl -s "https://app.hivel.ai/hivelapi/public/v1/teams?search_term=platform&#x26;page_size=20&#x26;offset=0" \
</strong>  -H "Authorization: Bearer &#x3C;HIVEL_PUBLIC_API_TOKEN>"
</code></pre>

**example:**

<pre><code><strong>curl -s "https://app.hivel.ai/hivelapi/public/v1/teams?search_term=platform&#x26;page_size=20&#x26;offset=0" \
</strong>  -H "Authorization: Bearer HIVEL_PUBLIC_API_2116_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
</code></pre>

**Response:** Same shape as Example 1, filtered to teams whose name matches `platform` and paginated according to `page_size`/`offset`.

3. **Hierarchical view**

**Request:**

```
curl -s "https://app.hivel.ai/hivelapi/public/v1/teams?flat=false" \
  -H "Authorization: Bearer <HIVEL_PUBLIC_API_TOKEN>"
```

**example:**

```
curl -s "https://app.hivel.ai/hivelapi/public/v1/teams?flat=false" \
  -H "Authorization: Bearer HIVEL_PUBLIC_API_2116_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

**Response:**

{% code expandable="true" %}

```
{
  "total": 2,
  "items": [
    {
      "id": 101,
      "name": "Platform",
      "organizationId": 2116,
      "teamType": "PUBLIC",
      "parentTeamId": null,
      "ownerName": "Jane Doe",
      "createdAt": "2025-01-10T09:00:00",
      "state": "ACTIVE",
      "subTeamCount": 1,
      "subTeams": [
        {
          "id": 102,
          "name": "Platform - Infra",
          "organizationId": 2116,
          "teamType": "PUBLIC",
          "parentTeamId": 101,
          "ownerName": "John Smith",
          "createdAt": "2025-02-03T11:30:00",
          "state": "ACTIVE",
          "subTeamCount": 0,
          "subTeams": []
        }
      ]
    }
  ]
}
```

{% endcode %}

`items` contains only top-level teams (`parentTeamId == null`); children are nested under `subTeams` rather than repeated at the root. `offset` and `page_size` are ignored in this mode.

### Error Handling

Every non-2xx response follows this shape:

```
{ "error": { "code": "<CODE>", "message": "<human-readable>", "requestId": "<uuid>" } }
```

<table data-search="false"><thead><tr><th width="110.89453125">Status</th><th width="234.61328125">Code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>INVALID_SEARCH_TERM</code></td><td><code>search_term</code> exceeds 100 characters</td></tr><tr><td>400</td><td><code>INVALID_PAGE_SIZE</code></td><td><code>page_size</code> is outside 1–50</td></tr><tr><td>400</td><td><code>INVALID_OFFSET</code></td><td><code>offset</code> is negative</td></tr><tr><td>401</td><td><code>MISSING_TOKEN</code></td><td>No <code>Authorization</code> header present</td></tr><tr><td>401</td><td><code>MALFORMED_TOKEN</code></td><td>Header present but not a recognizable key format</td></tr><tr><td>403</td><td><code>INVALID_TOKEN</code></td><td>Well-formed but inactive, expired, or unknown key</td></tr><tr><td>429</td><td><code>RATE_LIMITED</code></td><td>Rate limit exceeded - response includes a <code>Retry-After</code> header</td></tr></tbody></table>