> 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. # Events ## Create or update events `POST /events/` pushes event data to Hive. Events are matched by `event_id`. Send between 1 and 50 events per request. **Required scope:** `events:write` ```json { "events": [ { "event_id": "evt_45678", "name": "Summer Music Festival 2026", "event_url": "https://example.com/events/summer-fest", "start_at": "2026-07-15T18:00:00Z", "updated_at": "2026-02-10T12:00:00Z", "end_at": "2026-07-15T23:00:00Z", "doors_open_at": "2026-07-15T17:00:00Z", "presale_start_at": "2026-03-01T10:00:00Z", "onsale_start_at": "2026-03-15T10:00:00Z", "description": "The biggest summer music event of the year!", "primary_performer_names": ["The Headliners"], "supporting_performer_names": ["Opening Act"], "thumbnail_url": "https://example.com/images/summer-fest.jpg", "genres": ["Rock", "Indie"], "tags": ["outdoor", "festival"], "has_tickets_available": true, "total_tickets": 5000, "timezone": "America/Toronto", "venue": { "name": "Central Park Amphitheatre", "address": "100 Park Ave", "city": "Toronto", "state": "Ontario", "country": "Canada", "zip": "M5V 2H1" }, "tiers": [ { "tier_id": "tier_ga", "name": "General Admission", "price": 45.0 }, { "tier_id": "tier_vip", "name": "VIP", "price": 150.0 } ] } ] } ``` ### Fields | Field | Required | Description | | ---------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `event_id` | Yes | Your event ID | | `name` | Yes | Event name | | `event_url` | Yes | URL of the event page. Must be a valid URL. | | `start_at` | Yes | ISO 8601 datetime | | `updated_at` | Yes | ISO 8601 datetime | | `end_at`, `doors_open_at`, `presale_start_at`, `onsale_start_at` | No | ISO 8601 datetimes | | `description` | No | | | `primary_performer_names`, `supporting_performer_names` | No | Arrays of non-blank strings | | `thumbnail_url` | No | Must be a valid URL | | `genres`, `tags` | No | Arrays of non-blank strings | | `has_tickets_available`, `total_tickets` | No | Boolean; integer `>= 0` | | `timezone` | No | Non-blank string. Use an IANA timezone (for example, `America/Toronto`). | | `venue` | No | Object with `name` (required), plus optional `address`, `city`, `state`, `country`, `zip`. Sub-fields that are present must be non-blank. | | `tiers` | No | Array of ticket tiers, each with `tier_id`, `name`, and `price` (all required) | | `properties` | No | Custom event property values. See [Custom event property values](#custom-event-property-values). | Send datetimes as ISO 8601 strings with a UTC offset (for example, `2026-07-15T18:00:00-04:00` or `2026-07-15T18:00:00Z`). Datetimes without an offset are read in the `America/Toronto` timezone. The endpoint is asynchronous and returns `202 Accepted`. See [How It Works](/docs/how-it-works). > **Warning** > > Validation is all-or-nothing. If any event in the batch fails validation, the request returns > `422 Unprocessable Entity` and none of the events are saved. ### Custom event property values `properties` sets values for [custom event properties](#custom-event-properties) on the event. Keys are property names; values are strings or numbers. * Each name must match an existing property definition. Names are matched case-insensitively, and the same name can't appear twice (for example, `Presented_By` and `presented_by`). * Names are non-empty and up to 255 characters. * At most 100 properties per event. * Text values are non-blank strings of up to 1000 characters. Number values must be finite. * Each value must match the property's `value_type`: a string for `text`, a number for `number`. Property values are checked synchronously. An unknown property name or a type mismatch returns `422 Unprocessable Entity` before anything is queued: ```json { "events": { "0": { "properties": [ "Custom event property 'capacity_tier' expects a number value, got text." ] } } } ``` ## Partially update an event `PATCH /events/{event_id}/` updates individual fields on an event that already exists in Hive. Send only the fields that changed. **Required scope:** `events:write` ```json { "has_tickets_available": false, "properties": { "presented_by": "Live Nation" } } ``` * The body accepts the same fields as `POST /events/`, all optional, but must include at least one. * `event_id` comes from the path, not the body. `updated_at` is set by Hive when the update is applied. * Returns `202 Accepted`. Errors: * `404 Not Found`: no event with that `event_id` exists. Create it with `POST /events/` first. * `409 Conflict`: the event can't be partially updated. Re-send the full event with `POST /events/`. * `422 Unprocessable Entity`: the body is empty, a field is invalid, or a [property value](#custom-event-property-values) is invalid. ## Custom event properties Custom event properties let you define your own metadata fields for events. These endpoints manage the **property definitions**: the named, typed fields available to the authorized brand's events. > **Note** > > Unlike the push endpoints, custom event property endpoints are **synchronous**. Changes take > effect immediately and the response body contains the result. There's no `202` or background > processing step. ### The property object | Field | Description | | ------------- | ------------------------------------------------------------------------------ | | `id` | Hive's ID for the property (integer). Use it in the single-property endpoints. | | `name` | Property name. Names are unique per brand, compared case-insensitively. | | `value_type` | One of `text`, `number` | | `created_at` | ISO 8601 timestamp when the property was created | | `value_count` | Number of events that currently have a value for this property | Error responses for `404` and `409`, and for the property limit, have the form `{"errors": ["..."]}`. ### Endpoints | Method and path | Scope | Description | | ------------------------------------------------- | -------------- | ---------------------------------------------------------------------------- | | `GET /events/custom-properties/` | `events:read` | List properties (paginated) | | `POST /events/custom-properties/` | `events:write` | Create a property. Returns `201 Created`. | | `GET /events/custom-properties/{property_id}/` | `events:read` | Get one property | | `PUT /events/custom-properties/{property_id}/` | `events:write` | Rename and/or retype a property. Returns `200 OK` with the updated property. | | `DELETE /events/custom-properties/{property_id}/` | `events:write` | Delete a property. Returns `204 No Content`. | ### List properties `GET /events/custom-properties/` accepts `limit` (default `500`, range `0`–`500`) and `offset` (default `0`). An out-of-range `limit` returns `422 Unprocessable Entity`. ```json { "offset": 0, "limit": 500, "total_items": 2, "items": [ { "id": 101, "name": "presented_by", "value_type": "text", "created_at": "2026-08-20T14:30:00Z", "value_count": 12 }, { "id": 102, "name": "capacity_tier", "value_type": "number", "created_at": "2026-08-21T09:00:00Z", "value_count": 0 } ] } ``` ### Create a property ```json { "name": "presented_by", "value_type": "text" } ``` * `name` (required): up to 255 characters, non-empty. Must be unique within the brand, compared case-insensitively. * `value_type` (required): `text` or `number`. Returns `201 Created` with the new property object. Errors: * `409 Conflict`: a property with this name already exists for the brand. * `422 Unprocessable Entity`: `name` or `value_type` is invalid. * `422 Unprocessable Entity`: the brand has reached the maximum of **100** custom event properties. Delete one before creating another. ### Update a property `PUT /events/custom-properties/{property_id}/` is a full replacement: send both `name` and `value_type`, even if only one is changing. Errors: * `404 Not Found`: no property with that ID exists for the authorized brand. * `409 Conflict`: another property with this name already exists, or the property already has values and its type can't change. * `422 Unprocessable Entity`: `name` or `value_type` is invalid. > **Warning** > > A property's `value_type` is **locked once any event has a value for it** (`value_count` > 0). Re-sending the current type is always allowed. To change the type of a property that has values, delete it and create it again with the new type. ### Delete a property Deleting a property also deletes all of its values from your events. If the property has values on one or more events, the request fails with `409 Conflict` and the error message says how many events are affected. Re-send with the `force=true` query parameter to confirm deletion of the property and all of its values. ``` DELETE /events/custom-properties/101/?force=true ``` `force` is a boolean; an invalid value returns `422 Unprocessable Entity`. An unknown `property_id` returns `404 Not Found`. On success the response is `204 No Content`.