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.

   
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: HIVEL_PUBLIC_API_2116_a1b2c3d4-e5f6-7890-abcd-ef1234567890

   

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.

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:

https://app.hivel.ai

Endpoint:

GET /hivelapi/public/v1/teams

This single endpoint covers three use cases - retrieving all teams, searching teams, and viewing them in a hierarchical structure - controlled entirely by query parameters.

Query Parameters

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

Response Shape

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

• Every response also includes rate-limit information via the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset 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

Field	Type	Notes
id	int	Unique identifier for the team.
name	string	The team's display name.
organizationId	int	ID of the organization the team belongs to.
teamType	string | null	Raw value - no fixed enum.
parentTeamId	int | null	ID of the parent team. null indicates a top -level team.
ownerName	string | null	Display name of the team's owner. null if no owner is set.
createdAt	ISO datetime | null	Timestamp when the team was created. null if unavailable.
state	string	"ACTIVE" or "DELETED".
subTeamCount	int	Number of direct child teams. Only present when flat=false.
subTeams	array	Empty in flat mode; contains nested child team objects in hierarchical mode. Only present when flat=false.

Use Cases

1. Retrieve all teams (flat, default)

Request:

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:

{
  "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"
    }
  ]
}

1. Search teams by name

Request:

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

example:

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

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

1. 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:

{
  "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": []
        }
      ]
    }
  ]
}

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>" } }

Status	Code	When
400	INVALID_SEARCH_TERM	search_term exceeds 100 characters
400	INVALID_PAGE_SIZE	page_size is outside 1–50
400	INVALID_OFFSET	offset is negative
401	MISSING_TOKEN	No Authorization header present
401	MALFORMED_TOKEN	Header present but not a recognizable key format
403	INVALID_TOKEN	Well-formed but inactive, expired, or unknown key
429	RATE_LIMITED	Rate limit exceeded - response includes a Retry-After header