Hiver Omni Apis-Public

## Sections
• [Hiver Omni APIs](https://developer.hiverhq.com/hiver-omni-api/introduction.md): Overview The Hiver Omni APIs 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 APIs → Create API Key. Authorization: Bearer <your_api_token> Important: Copy and store it securely 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 the page query parameter. Paginated responses include a meta object: JSON "meta": { "current_page": 1, "total_pages": 5, "total_count": 48 }
• [Inboxes](https://developer.hiverhq.com/hiver-omni-api/inboxes.md): Manage inboxes, users within inboxes, and tags at the inbox level
  • [List all inboxes](https://developer.hiverhq.com/hiver-omni-api/inboxes/list-all-inboxes.md): Returns all shared inboxes accessible belonging to the account identified by the authentication token. The list will be empty if there are no inboxes configured.
  • [List users in an inbox](https://developer.hiverhq.com/hiver-omni-api/inboxes/list-users-in-an-inbox.md): Returns all users who have access to the specified inbox.
  • [List all tags in an inbox](https://developer.hiverhq.com/hiver-omni-api/inboxes/list-all-tags-in-an-inbox.md): Returns all tags configured at the inbox level. By default, only active tags are returned.
  • [Create a new tag](https://developer.hiverhq.com/hiver-omni-api/inboxes/create-a-new-tag.md): 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.
  • [Update a tag](https://developer.hiverhq.com/hiver-omni-api/inboxes/update-a-tag.md): Updates properties of an existing tag within the specified inbox. If the tag name is being updated, it must remain unique within the inbox.
• [Conversations](https://developer.hiverhq.com/hiver-omni-api/conversations.md): Manage conversations within inboxes and retrieve messages
  • [List conversations in an inbox](https://developer.hiverhq.com/hiver-omni-api/conversations/list-conversations-in-an-inbox.md): 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.
  • [Update a conversation](https://developer.hiverhq.com/hiver-omni-api/conversations/update-a-conversation.md): 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). Do note that it needs all the tag ids that needs to be present on the conversation. Say a conversation has tag A applied, if the tag_ids sends tag B, then. tag A is removed and tag B is applied.
  • [List messages in a conversation](https://developer.hiverhq.com/hiver-omni-api/conversations/list-messages-in-a-conversation.md): Returns all messages for the specified conversation, sorted by creation date.
• [Rate limiting](https://developer.hiverhq.com/hiver-omni-api/rate-limiting.md): API requests are rate-limited to 60 requests per minute per token. Exceeding this limit will return a 429 Too Many Requests response. Exponential Backoff On the first 429 response, wait 1 second before retrying. If still rate-limited, wait 2 seconds before the next retry. Continue doubling the wait time: 4s → 8s → 16s , up to a maximum of 60 seconds . Add a small random jitter (0–500ms) to each wait to prevent thundering herd problems when multiple clients retry simultaneously. If a Retry-After header is present, always prefer its value over the calculated backoff. Requests are rate-limited to approximately 1 request per second , with limited burst capacity. Distribute requests evenly across the minute to avoid throttling. Python 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) Important: Do not retry indefinitely. Set a maximum number of retries (recommended: 5) and surface the error to the caller if all retries are exhausted.