Uploads

Prepare an image upload

Prepares the upload of one local image (PNG, JPEG, WebP or GIF, at most 15 MB; no SVG) for a Help Center article or a changelog.

POST

/v2/uploads

curl --request POST \
  --url https://do.featurebase.app/v2/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contentType": "image/png",
  "filename": "billing-settings.png",
  "size": 284113
}
'

{
  "curlCommand": "curl -sS -X PUT --data-binary @<path> -H 'Content-Type: image/png' 'https://do.featurebase.app/v2/uploads/…'",
  "expiresAt": "2026-11-08T12:10:00.000Z",
  "headers": {
    "Content-Type": "image/png"
  },
  "id": "upl_0f6b2c1d9e8a4b7c8d9e0f1a2b3c4d5e",
  "method": "PUT",
  "object": "upload",
  "uploadUrl": "https://do.featurebase.app/v2/uploads/upl_0f6b2c1d9e8a4b7c8d9e0f1a2b3c4d5e/content?token=…"
}

Call this with the file name, the real contentType and the exact size in bytes.
Send the file with one PUT to uploadUrl within 10 minutes, with the returned headers. curlCommand does it: replace <path> with the file path. No API key is needed for the PUT: the URL is the credential.
The PUT answers { key, imgHtml }. Put imgHtml (<img src="" data-featurebase-content-key="…">) into an article body (formatter: 'raw' or 'default') or a changelog's htmlContent within 24 hours. Saving moves the image into that article or changelog.

One file per upload. Never send the image as base64 in a body.

PUT errors: 403 the token is not valid · 404 no such upload · 409 the file was already sent · 410 the URL expired (prepare again) · 411 no Content-Length · 400 the size is not the declared size · 413 larger than declared · 415 the Content-Type header or the bytes are not the declared image type (SVG is refused) · 429 too many uploads · 503 try again.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

contentTypeenum<string>required

The real type of the image. The bytes are checked against it. SVG is not accepted.

Available options: image/png, image/jpeg, image/webp, image/gif

Example: image/png

filenamestringrequired

The file name, e.g. billing-settings.png. Only used for the stored name.

Required string length: 1 - 200

Example: billing-settings.png

sizeintegerrequired

The exact size of the file in bytes (wc -c < file). At most 15 MB.

Required range: 1 <= x <= 15728640

Example: 284113

Response

Created

curlCommandstringrequired

The PUT as a curl command. Replace <path> with the local file path and run it in a shell.

Example: curl -sS -X PUT --data-binary @<path> -H 'Content-Type: image/png' 'https://do.featurebase.app/v2/uploads/…'

expiresAtstringrequired

When the upload URL stops working.

Example: 2026-11-08T12:10:00.000Z

headersobjectrequired

Send these headers with the PUT (exactly).

Show child attributes

idstringrequired

The upload id.

Example: upl_0f6b2c1d9e8a4b7c8d9e0f1a2b3c4d5e

methodenum<string>required

Available options: PUT

objectenum<string>required

Available options: upload

uploadUrlstringrequired

Send the file here with one PUT, within 10 minutes. The URL is the credential: do not share it.

Example: https://do.featurebase.app/v2/uploads/upl_0f6b2c1d9e8a4b7c8d9e0f1a2b3c4d5e/content?token=…

Still need help? Ask the team