Multipart upload metadata

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"
}

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, and there is no Worker script.
  • 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.

• usage_model string optional

  • Usage model to apply to invocations, only allowed value is standard.

Additional attributes: Workers Script Upload API

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

Note

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.

Additional attributes: Version Upload API

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

Note

These attributes are not available for immediately deployed uploads.

• 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.

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": "tail_consumer",
      "service": "<WORKER_NAME>"
    },
    {
      "type": "vectorize",
      "name": "<VARIABLE_NAME>",
      "index_name": "<INDEX_NAME>"
    },
    {
      "type": "version_metadata",
      "name": "<VARIABLE_NAME>"
    }
  ]
}

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!