The Hive REST API lets you read and change the data in your Hive workspaces from your own tools. Every endpoint lives under `https://app.hive.com/api/v2`. The SCIM 2.0 endpoints at the end of this reference are served from their own base URL, `https://scim.hive.com/v2/{workspaceId}`. ## Authentication Every request authenticates with one of: 1. An `api_key` request header. 2. An `api_key` query parameter. 3. An `Authorization: Bearer ` header (OAuth2 access token). 4. An `access_token` query parameter. API keys are created in the Hive app under **My Settings > API Info**. The acting user is the owner of the key or the token, and every endpoint applies that user's permissions. ```http GET /api/v2/workspaces//actions api_key: ``` Requests are limited to 1000 per minute per user; beyond that the API answers `429`. ## Responses and errors Successful responses are JSON (`content-type: application/json`). A single-resource endpoint returns the resource, or a message object such as `{ "message": "Action successfully deleted" }`. A delete answers with a JSON success payload, never an empty body, and keeps Hive's soft-delete semantics where the resource is soft-deleted. Errors use one JSON shape: ```json { "error": 400, "message": "Bad Request" } ``` | Status | Meaning | | --- | --- | | `400` | Validation failure or malformed request | | `403` | The user may not access the resource | | `404` | The resource does not exist | | `429` | Rate limit exceeded | | `500` | Unexpected server error | ## Cursor pagination List endpoints return a page of edges and a `pageInfo` object: ```json { "edges": [{ "cursor": "", "node": {} }], "pageInfo": { "startCursor": "", "endCursor": "", "hasPreviousPage": false, "hasNextPage": true, "totalCount": 123 } } ``` | Parameter | Meaning | | --- | --- | | `first` | Page size from the start of the list | | `last` | Page size from the end of the list | | `after` | Cursor from a previous response, for the next page | | `before` | Cursor from a previous response, for the previous page | | `total_count` | Set to `true` to include `pageInfo.totalCount` (opt-in because counts can be expensive) | `first` and `last` are mutually exclusive, must be positive integers, and are capped at 200. Cursors are opaque base64 values derived from the sort field and `_id`; pass them back unchanged. ```text GET /api/v2/workspaces//actions?first=25 GET /api/v2/workspaces//actions?first=25&after= GET /api/v2/workspaces//actions?last=25&before= GET /api/v2/workspaces//actions?first=25&total_count=true ``` ## Sorting `sortBy= `, for example `sortBy=createdAt desc` or `sortBy=name asc`. Each endpoint documents its sortable fields. The direction is `asc` or `desc`. Without `sortBy`, an endpoint uses a stable default order, and `_id` breaks ties so pages never skip or repeat items. ## Filtering Filters use bracketed query parameters: ```text filters[status]=Completed filters[archived]=false filters[customField-]=value ``` Each endpoint documents the filters it supports; an unsupported filter answers `400`. Values `true`, `false` and numbers are read as booleans and numbers; other values are JSON when they parse as JSON. Endpoints that filter by date use the `startDate` and `endDate` query parameters, as ISO 8601 values. ## Creating and updating - `POST` creates a resource and returns it, or a wrapper with a success message. Bodies are JSON. - `PUT` updates a single resource. `PATCH` updates part of a resource, or many at once. - Only allowlisted fields are accepted on update. ## Dashboard widget export Chart builder dashboard widgets export through an asynchronous job. The server starts a background export, waits up to about 20 seconds, then returns either a download URL or a poll URL for exports that take longer. Handle both. **Start an export:** `GET /api/v2/dashboard-widgets//export` | Parameter | Default | Values | | --- | --- | --- | | `type` | `default` | `default`, `detailed` | | `format` | `csv` | `csv`, `json` | `detailed` exports take longer and are more likely to need polling. ```json { "jobId": "", "status": "pending | running | completed", "pollUrl": "/api/v2/dashboard-widget-export-jobs/", "metadata": { "widgetId": "", "widgetType": "", "exportType": "default | detailed", "format": "csv | json" }, "fileUrl": "https://..." } ``` `fileUrl` is present only when the export completed within the wait window; `pollUrl` is always returned. A `400` answers an invalid `type` or `format`, a widget that cannot be exported (`Widget not found`, `Widget type does not support export`, `Dashboard not found for this widget`, `User filter not found`), or an export that failed; a `500` means the export could not be queued. **Poll a job:** `GET /api/v2/dashboard-widget-export-jobs/`. Only the user who started the export can read the job (`403` otherwise, `404` when it does not exist). ```json { "jobId": "", "status": "pending | running | completed | failed", "metadata": { "widgetId": "", "widgetType": "", "exportType": "default", "format": "csv" }, "createdAt": "2026-06-08T12:00:00.000Z", "fileUrl": "https://...", "error": "Dashboard widget export timed out.", "completedAt": "2026-06-08T12:05:00.000Z" } ``` `fileUrl` is present when `status` is `completed`; `error` when it is `failed`; `completedAt` once the job has finished. A job with no progress for about 30 minutes is marked `failed` with `Dashboard widget export timed out.`. Jobs are kept for 72 hours. Recommended client flow: call the export endpoint; if it returns `fileUrl`, download it and stop; otherwise poll `pollUrl` every 1 to 2 seconds until `status` is `completed` or `failed`.

400Bad Request