Skip to main content
A theme background image takes two steps. First store the image and get a signed_id. Then pass the signed_id as background_image when you create or update a theme. The image must be a PNG, JPEG, GIF or SVG of 1 MB or smaller. A signed_id works only in the workspace that created it, and only after the image bytes are uploaded.

​
Option 1: The image is on the web

1

Store the image

Send the public https address to Upload an image from a URL. The address must be reachable without credentials and point to a public host. At most 2 redirects are followed.
The response has the signed_id.
2

Use it on a theme

​
Option 2: The image is on your machine

1

Reserve the upload

Send the file name, its size in bytes and its checksum to Reserve an image upload. The checksum is the base64-encoded MD5 digest of the file, not the hex digest.
The response has the signed_id, the upload_url and the upload_headers.
2

Send the bytes

Send the file with an HTTP PUT to upload_url. Send every header in upload_headers unchanged. The upload_url is a short-lived credential, so do not share or log it.
Use the headers from the response. Do not add an X-Api-Key header to this request.
3

Use it on a theme

Pass the signed_id as background_image, as in option 1. A signed_id used before its bytes arrive returns a 422 error.
These properties go in theme.properties: Send an empty string or null as background_image to remove the image. Theme responses return background_image_url, the CDN address of the image, or null when there is none.