> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# API Reference

The API Reference documents every endpoint's parameters, request body, and responses. For concepts and usage guidance, see the [guides](/docs/contacts).

## Base URL

```
https://api.hive.co/v2
```

## Authentication

Every request needs an OAuth 2.0 access token and your client ID:

```
Authorization: Bearer <access_token>
X-Partner-Id: <client_id>
```

See [Authentication & Authorization](/docs/auth) to get a token and for the required scopes.

## Conventions

* **Brand-scoped**: tokens are scoped to a single brand, so no brand identifier is passed in requests.
* **Asynchronous writes**: data push endpoints return `202 Accepted` and process in the background. Segment and custom event property management endpoints respond synchronously (`200`, `201`, or `204`). See [How It Works](/docs/how-it-works).
* **Batches**: up to 50 items and 1 MB per request, validated all-or-nothing.
* **Pagination**: list endpoints use `limit` and `offset` (default `0`), and return `offset`, `limit`, `total_items`, and `items`. Defaults differ by endpoint: segment users default to `500`, campaign lists to `50`; both allow `0`–`500`. Out-of-range values return `422 Unprocessable Entity`.
* **Optional fields**: omit an optional field rather than sending `null`; an explicit `null` is rejected. Unknown fields are ignored.
* **Timestamps**: ISO 8601 (for example, `2026-02-10T14:30:00Z`). Include a UTC offset when sending datetimes.
* **IDs**: treat all IDs as opaque strings.
* **Health check**: `GET /ping/` requires no authentication and returns `{"status": "ok"}`.
* **Errors**: see [Errors & Status Codes](/docs/errors-status-codes).