Skip to navigation
Overview

API Reference

Endpoint-level reference for the Hive API V2

View as Markdown

The API Reference documents every endpoint’s parameters, request body, and responses. For concepts and usage guidance, see the guides.

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