GEgetsitecontrol
Images

Upload an image to the site's image library

Adds a file to the site's image library and returns it with its public url, which the widget and email image tools take. Give the file by url, a public http or https address it is downloaded from, or by data, base64-encoded with its name, for small content up to about 20 KB such as an icon or a logo.

A file is at most 3 MB; images of any common format are accepted. The file appears in the editors' Upload tab as well.

post/v1/sites/{site_id}/images

Request

  • Base URL
    https://api.getsitecontrol.com
  • Auth
    HTTP bearer

Path parameters

site_idinteger required

Headers

Idempotency-Keystring

Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with Idempotency-Replayed: true instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.

Request body

urlstring nullable

Public http or https address of the file to download, e.g. a photo or a generated image. Give it or data, not both

datastring nullable

The file itself, base64-encoded, for small content up to about 20 KB such as an icon or a logo. Give it or url, not both

namestring nullable

File name with its extension, e.g. logo.png. Required with data; with url it defaults to the last part of the address

Response

Successful Response

idinteger required
namestring nullable

File name with its extension, as it was uploaded; image.<ext> for a file sent to an upload link

urlstring required

Public address of the image. The widget and email image tools take this URL, e.g. as the hero image or an image block's source

widthinteger nullable

Pixels; null when the file's header does not say, as for SVG

heightinteger nullable

Pixels; null when the file's header does not say, as for SVG

updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.