Prepare a form-element attachment upload

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
}
'

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

Attachments

Prepare a form-element attachment upload

Prepare a 2-step upload for a form-element image. purpose selects the kind: header_image / wallpaper_image (theme images), rich_text_image, or a field-element image (choice_image, product_image, booking_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 consume the upload_id: theme images go into a theme update (header.images[].upload_id / wallpaper.image.upload_id); rich_text_image is finalized via POST /api/v1/attachment_commitments; field-element images go into the form create / update fields payload (choices[].image.upload_id, goods_items[].images[].upload_id, reservation_items[].images[].upload_id). No PAT scope required.

POST

api

attachments

Prepare a form-element attachment upload

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
}
'

{
  "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 / wallpaper_image are theme images consumed by a theme update; rich_text_image is finalized via POST /api/v1/attachment_commitments; choice_image / product_image / booking_image are field-element images referenced from the form create / update fields payload.

Available options:

header_image,

wallpaper_image,

rich_text_image,

choice_image,

product_image,

booking_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

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 consume the upload_id per its purpose: theme images in a theme update; rich_text_image via POST /api/v1/attachment_commitments; field-element images (choice_image / product_image / booking_image) inside the form create / update fields payload.

Show child attributes

Last modified on June 9, 2026

Update form settings Finalize prepared rich-text image uploads