Upload assets from a script

The asset library can be filled from a script as well as from the app. Use this when a pipeline should publish the images a site needs, such as screenshots built in CI, and a re-run must not create a second copy of a file that is already there.

Make a key

In Assets, open Settings and mint a management key. It has one of two levels:

Level	Can
Read	Find assets by the hash of a file, and read an asset
Write	Everything Read can, and upload files, create folders and make an asset public

You can only mint a Write key if you can upload, manage folders and make assets public yourself. A key is shown once, when you make it. It is a different kind of key from a channel key: a channel key reads what its channel allows, and cannot manage anything.

Send the key as a bearer token to /assets/management/v1. It is for servers and pipelines, not browsers.

Find before you upload

Take the SHA-256 of the file, in lowercase hexadecimal, and ask for it with Find assets by the hash of the file. Send up to 50 hashes at once. An asset that was uploaded from those exact bytes comes back with its assetId; a hash nothing was uploaded from is missing from the answer.

The hash is of the file you sent. Assets re-encode an image and rebuild an SVG when they store it, so the hash of a file you download from the library will not match. Assets uploaded in the app before this lookup existed have no hash and are never found.

Upload what is missing

1. Start an upload with the file’s kind, sizeBytes, filename and contentType. Ask for visibility: "public" if the file is for a public page.
2. Send the file to the URL in the answer, with a plain PUT and the headers it lists.
3. Complete the upload. The asset is created, and the answer is the asset.

Put the file in a folder with Make sure a folder exists, which creates a path like Website/Screenshots once and returns its id on every later call.

An asset that was uploaded private can be made public later with Make an asset public. That cannot be undone; delete the asset to take it back.

Limits

A key is held to the same limits as a person: your plan’s storage and public-image allowances, the size limit for each kind of file, and the check that a file is what it says it is. A request over a limit answers 403 with quota_exceeded.

Use the asset in your content

An asset reaches a page as a reference, by its assetId. See Assets in Content.