Skip to main content
Uploads

Prepare an image upload

Prepares the upload of one local image (PNG, JPEG, WebP, GIF or HEIC, at most 15 MB; no SVG) for a Help Center article, a changelog or a post. A HEIC photo (iPhone) is stored as JPEG, or PNG when it has transparency.

POST
/v2/uploads
  1. Call this with the file name, the real contentType and the exact size in bytes.
  2. 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. A browser can send the PUT from any origin, so your server can prepare the upload and give only uploadUrl and headers to your page. Never send your API key to a browser.
  3. The PUT answers { key, imgHtml }. Put imgHtml (<img src="" data-featurebase-content-key="…">) into an article body (formatter: 'raw' or 'default'), a changelog's htmlContent or a post's content within 24 hours. Saving moves the image into that article, changelog or post.

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) · 400 a HEIC photo that cannot be converted · 429 too many uploads · 503 try again.

Authorizationstringheaderrequired

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

Featurebase-Versionenum<string>header

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

Available options: 2026-09-03.pulsar, 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-09-03.pulsar

Body

application/json
contentTypeenum<string>required

The real type of the image. The bytes are checked against it. SVG is not accepted. A HEIC photo (image/heic, iPhone) is stored as JPEG, or PNG when it has transparency.

Available options: image/png, image/jpeg, image/webp, image/gif, image/heic
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

application/json

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).

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=…