Uploads

Use uploads to set a profile picture or banner, add a cover image to an event or post, attach a résumé to a job application, or add a file to quest evidence from a script. The API never accepts file bytes in its own JSON requests. You ask for a one-time upload URL, send the file to that URL, and then pass the storageId it returns in the request that uses the file.

API access needs a Honey Bee plan or above; see the developer overview. Errors and rate limits follow Requests, errors and limits.

#How an upload works

1. Request an upload URL

   Call POST /api/v1/uploads/url with the file name, type and size. You get a URL that is valid for 10 minutes and can be used once.

2. Send the file

   POST the raw bytes to the returned uploadUrl. The response contains the upload ID as storageId.

3. Attach the upload

   Send the storageId in the field that expects it, for example imageStorageId on a profile. Attach it within 24 hours; uploads that are not attached are deleted after that.

#Request an upload URL

curl -X POST https://app.hive3.tech/api/v1/uploads/url \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"image","fileName":"avatar.png","contentType":"image/png","byteSize":24000}'

const res = await fetch("https://app.hive3.tech/api/v1/uploads/url", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    purpose: "image",
    fileName: "avatar.png",
    contentType: "image/png",
    byteSize: 24000,
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://app.hive3.tech/api/v1/uploads/url",
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"]},
    json={"purpose": "image", "fileName": "avatar.png", "contentType": "image/png", "byteSize": 24000},
)
data = res.json()["data"]

{
  "data": {
    "uploadUrl": "https://example.com/upload?token=0123abcd",
    "purpose": "image",
    "fileName": "avatar.png",
    "contentType": "image/png",
    "maxBytes": 8388608
  }
}

#Send the file

Send the file bytes with a POST to the uploadUrl from the previous step. This request goes to the upload URL, not to the API: do not send the Authorization header, and set Content-Type to the file's MIME type. The URL works once, even when the upload fails, so request a new URL to retry.

curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @avatar.png

import { readFile } from "node:fs/promises";

const upload = await fetch(data.uploadUrl, {
  method: "POST",
  headers: { "Content-Type": "image/png" },
  body: await readFile("avatar.png"),
});
const { storageId } = await upload.json();

with open("avatar.png", "rb") as file:
    upload = requests.post(
        data["uploadUrl"], headers={"Content-Type": "image/png"}, data=file
    )
storage_id = upload.json()["storageId"]

Returns 200. This response is not wrapped in data, and errors are a plain error string rather than the API error object.

{ "storageId": "upload_123" }

#Attach an upload

Pass the storageId where a request accepts an upload ID. The upload must belong to the same key owner and have been requested with a matching purpose: image fields need an image upload, and attachment fields accept either. When the upload is attached, the file type and size are checked again against the stored file.

For example, set a profile picture with the upload ID from the previous step:

curl -X PATCH https://app.hive3.tech/api/v1/profile \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageStorageId":"upload_123"}'

• 400 invalid_request: the upload is not a valid ID, or its type or size is not allowed for that field (uploaded file type or size is not allowed by the upload policy).
• 404 not_found: the upload does not exist, has expired, belongs to another account, or was requested with a purpose the field does not accept (upload was not found).

#Limits

#AI assistant documents

Training documents for the AI assistant use their own route, POST /api/v1/ai-assistant/documents/upload-url, with different file types and a smaller size limit. It shares the account's upload URL budget. See AI assistant.

The hive3 upload command runs the whole flow for you; see the CLI command reference.