← Workers / workers / configuration

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.

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

The following attributes are configurable at the top-level.

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

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

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

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.

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