Direct Uploads
Our API empowers users to upload and include static assets as part of a Worker. These static assets can be served for free, and additionally, users can also fetch assets through an optional assets binding to power more advanced applications. This guide will describe the process for attaching assets to your Worker directly with the API.
sequenceDiagram participant User participant Workers API User<<->>Workers API: Submit manifest<br/>POST /client/v4/accounts/:accountId/workers/scripts/:scriptName/assets-upload-session User<<->>Workers API: Upload files<br/>POST /client/v4/accounts/:accountId/workers/assets/upload?base64=true User<<->>Workers API: Upload script version<br/>PUT /client/v4/accounts/:accountId/workers/scripts/:scriptName
The asset upload flow can be distilled into three distinct phases:
- Registration of a manifest
- Upload of the assets
- Deployment of the Worker
The asset manifest is a ledger which keeps track of files we want to use in our Worker. This manifest is used to track assets associated with each Worker version, and eliminate the need to upload unchanged files prior to a new upload.
The manifest upload request describes each file which we intend to upload. Each file is its own key representing the file path and name, and is an object which contains metadata about the file.
hash
represents a 32 hexadecimal character hash of the file, while size
is the size (in bytes) of the file.
The resulting response will contain a JWT, which provides authentication during file upload. The JWT is valid for one hour.
In addition to the JWT, the response instructs users how to optimally batch upload their files. These instructions are encoded in the buckets
field. Each array in buckets
contains a list of file hashes which should be uploaded together. Hashes of files that have been recently uploaded may not be returned in the API response; they do not need to be re-uploaded.
- Each file must be under 25 MiB
- The overall manifest must not contain more than 20,000 file entries
The file upload API requires files be uploaded using multipart/form-data
. The contents of each file must be base64 encoded, and the base64
query parameter in the URL must be set to true
.
The Authorization
header must be provided as a bearer token, using the JWT (upload token) from the aforementioned manifest upload call.
Once every file in the manifest has been uploaded, a status code of 201 will be returned, with the jwt
field present. This JWT is a final “completion” token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour.
Script and version upload endpoints require specifying a metadata part in the form data. Here, we can provide the completion token from the previous (upload assets) step.
If this is a Worker which already has assets, and you wish to just re-use the existing set of assets, we do not have to specify the completion token again. Instead, we can pass the boolean keep_assets
option.
Asset routing configuration can be provided in the assets
object, such as html_handling
and not_found_handling
.
Optionally, an assets binding can be provided if you wish to fetch and serve assets from within your Worker code.