> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.hive.co/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server. # API Reference ## API Docs - Hive API > Campaigns [List ad campaigns](https://developers.hive.co/api-reference/hive-api/campaigns/ads-retrieve.md) - Hive API > Campaigns [Get ad campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/ads-stats-retrieve.md) - Hive API > Campaigns [Get aggregate ad campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/ads-aggregate-stats-retrieve.md) - Hive API > Campaigns [List email campaigns](https://developers.hive.co/api-reference/hive-api/campaigns/email-retrieve.md) - Hive API > Campaigns [Get campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/email-stats-retrieve.md) - Hive API > Campaigns [Get aggregate campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/email-aggregate-stats-retrieve.md) - Hive API > Campaigns [List SMS campaigns](https://developers.hive.co/api-reference/hive-api/campaigns/sms-retrieve.md) - Hive API > Campaigns [Get SMS campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/sms-stats-retrieve.md) - Hive API > Campaigns [Get aggregate SMS campaign stats](https://developers.hive.co/api-reference/hive-api/campaigns/sms-aggregate-stats-retrieve.md) - Hive API > Contacts [Create or update contacts](https://developers.hive.co/api-reference/hive-api/contacts/create.md) - Hive API > Custom Properties [Delete custom properties from contacts](https://developers.hive.co/api-reference/hive-api/custom-properties/contacts-custom-properties-delete-create.md) - Hive API > Events [Create or update events](https://developers.hive.co/api-reference/hive-api/events/create.md) - Hive API > Events [Partially update an event](https://developers.hive.co/api-reference/hive-api/events/partial-update.md) - Hive API > Custom Event Properties [List custom event properties](https://developers.hive.co/api-reference/hive-api/custom-event-properties/events-custom-properties-retrieve.md) - Hive API > Custom Event Properties [Create custom event property](https://developers.hive.co/api-reference/hive-api/custom-event-properties/events-custom-properties-create.md) - Hive API > Custom Event Properties [Get custom event property](https://developers.hive.co/api-reference/hive-api/custom-event-properties/events-custom-property-retrieve.md) - Hive API > Custom Event Properties [Update custom event property](https://developers.hive.co/api-reference/hive-api/custom-event-properties/events-custom-properties-update.md) - Hive API > Custom Event Properties [Delete custom event property](https://developers.hive.co/api-reference/hive-api/custom-event-properties/events-custom-properties-destroy.md) - Hive API > Orders [Create or update orders](https://developers.hive.co/api-reference/hive-api/orders/create.md) - Hive API > Segments [List segments](https://developers.hive.co/api-reference/hive-api/segments/retrieve.md) - Hive API > Segments [Create segment](https://developers.hive.co/api-reference/hive-api/segments/create.md) - Hive API > Segments [Delete segment](https://developers.hive.co/api-reference/hive-api/segments/destroy.md) - Hive API > Segments [List segment users](https://developers.hive.co/api-reference/hive-api/segments/users-retrieve.md) - Hive API > Segments [Add users to segment](https://developers.hive.co/api-reference/hive-api/segments/users-create.md) - Hive API > Segments [Remove users from segment](https://developers.hive.co/api-reference/hive-api/segments/users-remove-create.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://developers.hive.co/openapi.json) - [OpenAPI YAML](https://developers.hive.co/openapi.yaml) > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.hive.co/api-reference/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 X-Partner-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).