For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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:

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:

Endpoint:

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

  • 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:

example:

Response:

  1. Search teams by name

Request:

example:

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

  1. Hierarchical view

Request:

example:

Response:

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:

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

Last updated