Multipart upload metadata (2)

Multipart upload metadata (2)

Last updated Jul 3, 2026 Note

There is a new API for uploading Workers. Refer to these docs for more information.

If you're using the Workers Script Upload API or Version Upload API directly, multipart/form-data uploads require you to specify a metadata part. This metadata defines the Worker's configuration in JSON format, analogue to the wrangler.toml file.

Sample `metadata`

{
    "main_module": "main.js",
    "bindings": [
        {
            "type": "plain_text",
            "name": "MESSAGE",
            "text": "Hello, world!"
        }
    ],
    "compatibility_date": "2021-09-14"
}

Note

See examples of metadata being used with the Workers Script Upload API here.

Attributes

The following attributes are configurable at the top-level.

Note

At a minimum, the main_module key is required to upload a Worker.

main_module string required
The part name that contains the module entry point of the Worker that will be executed. For example, main.js.
assets object optional
Asset configuration for a Worker.
config object optional
- html_handling determines the redirects and rewrites of requests for HTML content.
- not_found_handling determines the response when a request does not match a static asset.
jwt field provides a token authorizing assets to be attached to a Worker.
keep_assets boolean optional
Specifies whether assets should be retained from a previously uploaded Worker version; used in lieu of providing a completion token.
bindings array[object] optional
Bindings to expose in the Worker.
placement object optional
Smart placement object for the Worker.
mode field only supports smart for automatic placement.
compatibility_date string optional
Compatibility Date indicating targeted support in the Workers runtime. Backwards incompatible fixes to the runtime following this date will not affect this Worker. Highly recommended to set a compatibility_date, otherwise if on upload via the API, it defaults to the oldest compatibility date before any flags took effect (2021-11-02).
compatibility_flags array[string] optional
Compatibility Flags that enable or disable certain features in the Workers runtime. Used to enable upcoming features or opt in or out of specific changes not included in a compatibility_date.

Additional attributes: Workers Script Upload API

For immediately deployed uploads, the following additional attributes are configurable at the top-level.

Note

Except for annotations, these attributes are not available for version uploads.

migrations array[object] optional
Durable Objects migrations to apply.
logpush boolean optional
Whether Logpush is turned on for the Worker.
tail_consumers array[object] optional
Tail Workers that will consume logs from the attached Worker.
tags array[string] optional
List of strings to use as tags for this Worker.
annotations object optional
Annotations object for the Worker version created by this upload. Also available on the Version Upload API.
workers/message specifies a custom message for the version.
workers/tag specifies a custom identifier for the version.

Additional attributes: Version Upload API

For version uploads, the following additional attributes are configurable at the top-level.

annotations object optional
Annotations object specific to the Worker version.
workers/message specifies a custom message for the version.
workers/tag specifies a custom identifier for the version.
workers/alias specifies a custom alias for this version.

Bindings

Workers can interact with resources on the Cloudflare Developer Platform using bindings. Refer to the JSON example below that shows how to add bindings in the metadata part.

{
    "bindings": [
        {
            "type": "ai",
            "name": "<VARIABLE_NAME>"
        },
        {
            "type": "analytics_engine",
            "name": "<VARIABLE_NAME>",
            "dataset": "<DATASET>"
        },
        {
            "type": "assets",
            "name": "<VARIABLE_NAME>"
        },
        {
            "type": "browser_rendering",
            "name": "<VARIABLE_NAME>"
        },
        {
            "type": "d1",
            "name": "<VARIABLE_NAME>",
            "id": "<D1_ID>"
        },
        {
            "type": "durable_object_namespace",
            "name": "<VARIABLE_NAME>",
            "class_name": "<DO_CLASS_NAME>"
        },
        {
            "type": "hyperdrive",
            "name": "<VARIABLE_NAME>",
            "id": "<HYPERDRIVE_ID>"
        },
        {
            "type": "kv_namespace",
            "name": "<VARIABLE_NAME>",
            "namespace_id": "<KV_ID>"
        },
        {
            "type": "mtls_certificate",
            "name": "<VARIABLE_NAME>",
            "certificate_id": "<MTLS_CERTIFICATE_ID>"
        },
        {
            "type": "plain_text",
            "name": "<VARIABLE_NAME>",
            "text": "<VARIABLE_VALUE>"
        },
        {
            "type": "queue",
            "name": "<VARIABLE_NAME>",
            "queue_name": "<QUEUE_NAME>"
        },
        {
            "type": "r2_bucket",
            "name": "<VARIABLE_NAME>",
            "bucket_name": "<R2_BUCKET_NAME>"
        },
        {
            "type": "secret_text",
            "name": "<VARIABLE_NAME>",
            "text": "<SECRET_VALUE>"
        },
        {
            "type": "service",
            "name": "<VARIABLE_NAME>",
            "service": "<SERVICE_NAME>",
            "environment": "production"
        },
        {
            "type": "vectorize",
            "name": "<VARIABLE_NAME>",
            "index_name": "<INDEX_NAME>"
        },
        {
            "type": "version_metadata",
            "name": "<VARIABLE_NAME>"
        }
    ]
}

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/#page","headline":"Multipart upload metadata","description":"Define Workers configuration in JSON metadata for multipart form-data script uploads.","url":"https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/","inLanguage":"en","image":"https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/og.png?v=e03a6759be39ccfb","dateModified":"2026-07-03","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Control where your Worker runs to reduce latency. title: Placement image: https://developers.cloudflare.com/workers/configuration/placement/og.png?v=1bd74349c7db3306

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt
Use this file to discover all available pages before exploring further.

Multipart upload metadata (2)

Multipart upload metadata (2)

Sample metadata

Attributes

Additional attributes: Workers Script Upload API

Additional attributes: Version Upload API

Bindings

On this page

Sample `metadata`