Requests, errors and limits

Every endpoint follows the same conventions. Read this page once, then use the reference pages for the details of each area. All examples assume your key is in the HIVE_API_KEY environment variable; see Authentication and API keys.

#Base URL and requests

All paths are served under one base URL, over HTTPS only:

https://app.hive3.tech/api/v1

• Send request bodies as a JSON object with Content-Type: application/json. An array or any other JSON value returns 400 invalid_request.
• Send filters and pagination as query parameters.
• Identify the acting account only through the key. A request never needs, and cannot supply, a user ID as its authority.
• Request bodies have size limits, from 16 KiB for small updates up to 256 KiB for courses and content. A larger body returns 413 with the code invalid_request.
• The API is meant to be called from servers and scripts. Browsers on other websites are not allowed to call it, and a key placed in front-end code is exposed to every visitor.

#Response format

A successful response is a JSON object with a data field. List endpoints add a page object.

{ "data": { "id": "event_123", "title": "Portfolio night" } }

{
  "data": [{ "id": "event_123", "title": "Portfolio night" }],
  "page": { "nextCursor": "1793126400000", "hasMore": true }
}

Creates normally return 201; reads and updates return 200. Optional fields that are not set may be null or omitted; do not rely on a field being present unless the reference marks it as always returned. Some field names use the older words person and community where this documentation says account. Both are account IDs.

#Errors

Every response outside the 2xx range has the same shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "API key does not include the required scope",
    "requiredScopes": ["account:read"]
  }
}

Branch on code, which is stable. message is meant for people and can change. requiredScopes appears only on insufficient_scope errors.

A 404 is also returned when you ask for something you are not allowed to see, so that the API does not reveal whether it exists.

#Pagination

List endpoints accept limit and cursor unless the reference says otherwise.

Lists are newest first and leave out archived items. When page.hasMore is true, pass page.nextCursor as cursor to continue; nextCursor is null on the last page. Walking nextCursor until hasMore is false visits the whole set.

Two exceptions: notification lists use limit, offset and unreadOnly (Notifications), and several lists return a plain data array with no page object, capped as follows: event participants, course and quest enrollments, quest evidence and job applications (200 each), community applications (100) and members (200), plus wallets, linked communities and notification mutes. Notifications return { notifications, hasMore, total, unreadCount } inside data.

curl "https://app.hive3.tech/api/v1/events?limit=50&cursor=1793126400000" \
  -H "Authorization: Bearer $HIVE_API_KEY"

const base = "https://app.hive3.tech/api/v1";
const headers = { Authorization: `Bearer ${process.env.HIVE_API_KEY}` };
const events = [];
let cursor;
do {
  const url = new URL(`${base}/events`);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const { data, page } = await (await fetch(url, { headers })).json();
  events.push(...data);
  cursor = page.hasMore ? page.nextCursor : undefined;
} while (cursor);

import os, requests

base = "https://app.hive3.tech/api/v1"
headers = {"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}"}
events, cursor = [], None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    body = requests.get(f"{base}/events", headers=headers, params=params).json()
    events += body["data"]
    if not body["page"]["hasMore"]:
        break
    cursor = body["page"]["nextCursor"]

#Idempotency

Send an Idempotency-Key header on a create request so you can retry it after a timeout or dropped connection without creating a duplicate. It is read on these routes:

• POST to /posts, /events, /courses, /content, /quests and /jobs
• POST /broadcasts
• POST /ai-assistant/documents

curl https://app.hive3.tech/api/v1/events \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Idempotency-Key: portfolio-night-2026-11" \
  -H "Content-Type: application/json" \
  -d '{"title":"Portfolio night","description":"Bring two projects"}'

• Choose a unique value per intended action, such as a UUID or your own record ID. Keys are limited to 128 characters; longer values are cut.
• Keys are scoped to your account and remembered for 48 hours.
• A repeat with the same key, method, path and body returns the first response again, with the same status, and creates nothing new.
• A repeat with the same key but a different body or path returns 409 conflict with Idempotency key was already used with a different request.
• Only successful creates are remembered. If the first attempt failed, retrying with the same key runs it again.
• Other write routes ignore the header. Where an action is naturally repeatable, such as awarding a credential to someone who already has it, the reference says so.

#Rate limits

Limits protect the service and use fixed windows that start on the clock minute, hour or day, so a count resets at the next boundary rather than a fixed time after your first request.

• Account budget. All keys of one account share 600 requests per minute. Every request counts, including requests that fail with a missing scope.
• Route budgets. Writes and expensive reads also have their own budget per account, summarized below. Budgets for creating and changing resources are kept separately for each kind (events, courses and so on) and for each workflow area.

When a limit is reached the API returns 429 with the code rate_limited. Route budgets return Retry-After (seconds to wait), except on post likes, comment edits, deletes and likes, and the notification write routes. The 600-per-minute account budget also has no Retry-After. Budgets shared with the app (RSVP changes, credential awards, quest evidence) do return it. Build your client to handle both:

1. If Retry-After is present, wait at least that many seconds.
2. If it is absent, wait for the next clock minute and add random jitter, then retry with exponential backoff.
3. Spread bulk work over time instead of sending it in a burst, and retry only requests that are safe to repeat (reads, or creates sent with an Idempotency-Key).

A few limits return 400 invalid_request with a plain message instead of 429: the per-day and per-item budgets behind post and comment likes, the shared profile builder save budget, the daily data-export limit, and the AI assistant document attach limits. Plan and cadence rules from the app, such as how often a plan may send broadcasts, are reported as 400 or 403 the same way. Read error.message and do not retry those automatically. Budgets are counted against the key owner's account, including when the key acts on a managed account.

#Timestamps

Timestamps you send are ISO 8601 strings that include an offset, for example 2030-01-01T10:00:00.000Z or 2030-01-01T12:00:00+02:00. A value without Z or an offset is rejected rather than guessed from a time zone.

Timestamps in responses use two formats, depending on the object: