AI assistant

Returns the account's assistant. Before the first save it returns the defaults with id: null, isNew: true, the name AI Assistant and visibility public.

curl "https://app.hive3.tech/api/v1/ai-assistant?account=@design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200. visibility is public (anyone may chat), protected (accepted members and the account's team) or private (owner, admins and moderators only).

{
  "data": {
    "id": "assistant_123", "accountId": "account_123", "name": "Guild helper", "description": "Answers member questions",
    "avatarUrl": "", "visibility": "protected", "isNew": false, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:05:00.000Z"
  }
}

Errors: 403 forbidden (account below Honey Bee, or your role does not allow it), 403 insufficient_scope, 404 not_found (account not found).

Updates the assistant, and creates it on the first save. Send only the fields you change; the others keep their current value. Send an empty string for description or avatarUrl to clear it. The body can be up to 16 KiB.

curl -X PATCH "https://app.hive3.tech/api/v1/ai-assistant?account=@design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Guild helper","visibility":"protected"}'

const res = await fetch("https://app.hive3.tech/api/v1/ai-assistant?account=@design-guild", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.HIVE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Guild helper", visibility: "protected" }),
});
const { data } = await res.json();

import os, requests

res = requests.patch(
    "https://app.hive3.tech/api/v1/ai-assistant",
    params={"account": "@design-guild"},
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"]},
    json={"name": "Guild helper", "visibility": "protected"},
)
data = res.json()["data"]

Returns 200 with the assistant (same shape as the GET response), including on the first save.

Lists the assistant's documents, newest first. The list holds up to 50 documents and is not paginated. It is empty before the assistant is saved.

curl "https://app.hive3.tech/api/v1/ai-assistant/documents" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200. Add ?account= as in the settings route to read another account's documents.

{ "data": [{ "id": "document_123", "fileName": "handbook.pdf", "fileSize": 182044, "mimeType": "application/pdf", "extractionStatus": "done", "uploadedAt": "2026-10-27T18:06:00.000Z" }] }

Issues a single-use upload link, valid for 10 minutes, that you send the file to. It needs a Honey Bee account and takes no body. The upload belongs to the key owner, even when you attach it to another account's assistant.

curl -X POST "https://app.hive3.tech/api/v1/ai-assistant/documents/upload-url?account=@design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 201.

{
  "data": {
    "uploadUrl": "https://upload.example.com/upload?token=…",
    "maxBytes": 5242880,
    "contentTypes": ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "text/plain"]
  }
}

uploadUrl is an opaque address; use it exactly as returned. Send the raw file bytes in a POST to it with the file's Content-Type and no Authorization header. The reply is { "storageId": "<upload ID>" } (no data envelope), which you pass to the attach call. The upload host answers 400 for an unsupported type, an empty file or a file whose content does not match its type, 403 for an expired or used link, and 413 for a file over maxBytes.

Errors: 403 forbidden (account below Honey Bee, or your role does not allow it), 403 insufficient_scope, 404 not_found.

Attaches an uploaded file to the assistant and starts text extraction. Save the assistant first: with no saved assistant this returns 404. The route reads the Idempotency-Key header: repeating the request with the same key and body returns the first response, and the same key with a different body returns 409 conflict (idempotency). The body can be up to 4 KiB.

curl -X POST https://app.hive3.tech/api/v1/ai-assistant/documents \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storageId":"upload_123","fileName":"handbook.pdf","fileSize":182044,"mimeType":"application/pdf"}'

The walkthrough below runs this call in curl, JavaScript and Python. Returns 201 with the document, extractionStatus pending.

{ "data": { "id": "document_123", "fileName": "handbook.pdf", "fileSize": 182044, "mimeType": "application/pdf", "extractionStatus": "pending", "uploadedAt": "2026-10-27T18:06:00.000Z" } }

Deletes a document and its stored file. Anyone who may manage the account that owns the assistant can delete it; no plan check applies.

curl -X DELETE https://app.hive3.tech/api/v1/ai-assistant/documents/document_123 \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200.

{ "data": { "deleted": true, "id": "document_123" } }

Errors: 404 not_found (Document not found), 403 forbidden, 403 insufficient_scope, 429 rate_limited after 60 deletes in a minute.