Hiver

The Hiver Omni Public API enables programmatic access to manage inboxes, conversations, tags, and users within your Hiver workspace.

## Authentication
All API requests require a Bearer token passed in the `Authorization` header. You can generate an API token from the **Hiver Admin Panel → Settings → Developer → API**.

```
Authorization: Bearer <your_api_token>
```

> **Important:** The token is displayed only once upon creation. Copy and store it securely.

## Rate Limiting
API requests are rate-limited to **100 requests per minute** per token. Exceeding this limit will return a `429 Too Many Requests` response.

## Response Format
All successful responses follow this structure:
```json
{
  "data": { ... }
}
```

All error responses follow this structure:
```json
{
  "error_code": "ERROR_CODE",
  "error_message": "Human-readable error description"
}
```

## Pagination
List endpoints support pagination via `page` query parameter. Paginated responses include a `meta` object:
```json
{
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 48
  }
}
```


Hiver Omni APIs

Manage inboxes, users within inboxes, and tags at the inbox level

Inboxes

Returns all shared mailboxes and chat inboxes accessible to the user group identified by the authentication token.

The list will be empty if there are no inboxes configured.


List all inboxes

Returns all users who have access to the specified inbox.


List users in an inbox

Returns all tags configured at the inbox level. By default, only active tags are returned.


List all tags in an inbox

Creates a new tag within the specified inbox. The tag name must be unique within the inbox. If no color is provided, a default color will be assigned.


Create a new tag

Updates properties of an existing tag within the specified inbox. If the tag name is being updated, it must remain unique within the inbox.


Update a tag

Manage conversations within inboxes and retrieve messages

Conversations

Returns conversations in the specified inbox with optional filtering. Results are sorted by creation date in descending order (newest first) by default.

If no filters are provided, all conversations are returned with default pagination.


List conversations in an inbox

Updates properties of a conversation. You may update the assignee, status, or tags — but **only one property per request**.

- To update the assignee, provide `assignee_id`.
- To update the status, provide `status`.
- To update tags, provide `tag_ids` (array of active tag IDs to assign).


Update a conversation

Returns all messages for the specified conversation, sorted by creation date.


List messages in a conversation

Rate limiting

Default

Hiver Omni Apis-Public

Production

Staging

Sandbox

<p class="slate-p " ><h1 class="slate-h1 " >Overview</h1><p class="slate-p " >The Hiver Omni APIs enables programmatic access to manage inboxes, conversations, tags, and users within your Hiver workspace.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Authentication</h2><p class="slate-p " >All API requests require a Bearer token passed in the <code class="slate-code">Authorization</code> header. You can generate an API token from the <strong class="slate-bold">Hiver Admin Panel → Settings → Developer APIs → Create API Key.  </strong></p><p class="slate-p " ><code class="slate-code">Authorization: Bearer &lt;your_api_token&gt;</code></p><p class="slate-p " ><strong class="slate-bold">Important:</strong> Copy and store it securely</p></p><p class="slate-p " ></p><p class="slate-p " ><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h2 class="slate-h2 " >Response Format</h2><p class="slate-p " >All successful responses follow this structure:</p><p class="slate-p " ><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">&quot;data&quot;: { ... }</div></div></code></pre></div><p class="slate-p " ></p><p class="slate-p " >All error responses follow this structure:</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
    &quot;error_code&quot;: &quot;ERROR_CODE&quot;,
    &quot;error_message&quot;: &quot;Human-readable error description&quot;
}</div></div></code></pre></div><p class="slate-p " ></p></p></p><p class="slate-p " ><h2 class="slate-h2 " >Pagination</h2><p class="slate-p " >List endpoints support pagination via the <code class="slate-code">page</code> query parameter. Paginated responses include a <code class="slate-code">meta</code> object:</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">&quot;meta&quot;: {
    &quot;current_page&quot;: 1,
    &quot;total_pages&quot;: 5,
    &quot;total_count&quot;: 48
}</div></div></code></pre></div><p class="slate-p " ></p></p><p class="slate-p " ></p>

<p class="slate-p " >Manage inboxes, users within inboxes, and tags at the inbox level</p><p class="slate-p " ></p><p class="slate-p " ></p>

<p class="slate-p " >Manage conversations within inboxes and retrieve messages</p><p class="slate-p " ></p>

<p class="slate-p " >API requests are rate-limited to 60 requests per minute per token. Exceeding this limit will return a <span style="background-color:rgba(16, 16, 16, 0.02);color:rgba(20, 23, 25, 0.84)"><code class="slate-code">429 Too Many Requests</code></span> response. </p><p class="slate-p " ></p><h3 class="slate-h3 " >Exponential Backoff</h3><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">On the first <span style="background-color:rgba(16, 16, 16, 0.02);color:rgba(20, 23, 25, 0.84)"><code class="slate-code">429</code></span> response, wait <strong class="slate-bold">1 second</strong> before retrying.</div></li><li class="slate-li " ><div style="position:relative">If still rate-limited, wait <strong class="slate-bold">2 seconds</strong> before the next retry.</div></li><li class="slate-li " ><div style="position:relative">Continue doubling the wait time: <strong class="slate-bold">4s → 8s → 16s</strong>, up to a maximum of <strong class="slate-bold">60 seconds</strong>.</div></li><li class="slate-li " ><div style="position:relative">Add a small random jitter (0–500ms) to each wait to prevent thundering herd problems when multiple clients retry simultaneously.</div></li><li class="slate-li " ><div style="position:relative">If a <span style="background-color:rgba(16, 16, 16, 0.02);color:rgba(20, 23, 25, 0.84)"><code class="slate-code">Retry-After</code></span> header is present, always prefer its value over the calculated backoff.</div></li></ol><p class="slate-p " >Requests are rate-limited to approximately <strong class="slate-bold">1 request per second</strong>, with limited burst capacity. Distribute requests evenly across the minute to avoid throttling.</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Python</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-python keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">for attempt in 1..max_retries:
    response = make_api_request()
    if response.status != 429:
        break
    delay = min(base_delay * (2 ^ (attempt - 1)), 60)
    jitter = random(0, 0.5)
    sleep(delay + jitter)</div></div></code></pre></div><p class="slate-p " ></p><p class="slate-p " ><strong class="slate-bold">Important:</strong> Do not retry indefinitely. Set a maximum number of retries (recommended: 5) and surface the error to the caller if all retries are exhausted.</p><p class="slate-p " ></p><p class="slate-p " >
</p>

 per token. Exceeding this limit will return a 

Requests are rate-limited to approximately 

, with limited burst capacity. Distribute requests evenly across the minute to avoid throttling.

 Do not retry indefinitely. Set a maximum number of retries (recommended: 5) and surface the error to the caller if all retries are exhausted.

Sections