Prepare a form-element attachment upload

Prepare a 2-step upload for a form-element image (header_image or wallpaper_image). Returns a one-time upload_id and an upload_url.

Send the file to upload_url with an HTTP PUT: the raw file bytes as the request body and the Content-Type header set to the value you declared in content_type (it must match). Use the upload_url exactly as returned.

Then reference the upload_id as header.images[].upload_id or wallpaper.image.upload_id in a theme update — the theme update registers the attachment and derives the palette. No PAT scope required.

POST /api/v1/attachments

Prepare a form-element attachment upload

cURL

curl --request POST \
  --url https://formhug.ai/api/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_name": "cover.png",
  "content_type": "image/png",
  "file_size": 123456
}
'

200

{
  "data": {
    "upload_id": "<string>",
    "upload_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization · string · header · required

Personal Access Token prefixed with fh_. Sent as Authorization: Bearer fh_xxx. The scope required by each endpoint is listed in that endpoint's description.

Body

application/json

purpose · enum<string> · required

What this attachment is for. header_image is shown as the form's header image; wallpaper_image is a card-layout form background.

Available options: header_image, wallpaper_image

file_name · string · required

Original file name (with extension).

Example:

"cover.png"

content_type · string · required

MIME type. Must be one of image/jpeg, image/png, image/webp, image/gif. Pinned into the upload URL — the PUT must send this exact Content-Type.

Example:

"image/png"

file_size · integer · required

File size in bytes. Must be ≤ 5 MB.

Example:

123456

Response

200

application/json

Upload credentials issued

data · object · required

Prepare-step response for the 2-step form-element attachment upload. Send the file to upload_url with an HTTP PUT: the raw file bytes as the request body and the Content-Type header set to the value you declared in content_type (it must match). Use upload_url exactly as returned. Then reference the upload_id as header.images[].upload_id or wallpaper.image.upload_id in a theme update — the theme update registers the attachment.

Show child attributes