docs: update all content to reflect new Workers API

Author: markjmiller

src/content/changelog/workers/2025-08-11-new-workers-api.mdx

@@ -0,0 +1,78 @@
+---
+title: New Workers API that allows you to explicitly manage Workers, Versions, and Deployments
+description: New Workers API, SDK methods, and Terraform resources for explicitly managing Workers, Versions, and Deployments
+date: 2025-08-11
+---
+
+The current Workers script upload API and its corresponding SDK methods (i.e. [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) and [cloudflare-python](https://github.com/cloudflare/cloudflare-python)) and Terraform resource ([cloudflare_workers_script](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/workers_script)) are convenient for a one-shot Workers deployment, but sometimes that does too much. This API unavoidably creates a Version and a Deployment (see [Versions and Deployments](/workers/configuration/versions-and-deployments/)). However, these are separate resources you can individually manage, and sometimes you want more control over how and when these are created.
+
+In [Cloudflare Terraform Provider](https://registry.terraform.io/providers/cloudflare/cloudflare/5.9.0/docs) 5.9.0 and [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) 4.6.0 (TODO double check these versions), we're introducing a clean, separated API that makes Workers, Versions, and Deployments individual "capital R" resources with clear concerns. It's now possible to create a Worker entity--and reference it elsewhere--before uploading code, bindings, or making it routable from the internet. You'll also enjoy a more ergonomic modules upload interface vs the old multipart/form-data API.
+
+This example uses the [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) SDK library.
+
+```javascript
+const scriptContent = `
+  export default {
+    async fetch(request, env, ctx) {
+      return new Response(env.MESSAGE, { status: 200 });
+    }
+  };
+`;
+
+/**
+ * Create a Worker and set non-versioned settings like observability
+ */
+const worker = await client.workers.create("my-worker", {
+  account_id: "...",
+  observability: {
+    enabled: true,
+  },
+});
+
+/**
+ * Create the first version of the Worker
+ * This is where code and bindings are defined and can be different between versions
+ */
+const version = await client.workers.versions.create(worker.id, {
+  account_id: "...",
+  main_module: "my-worker-script",
+  compatibility_date: $today,
+  bindings: [ /*...*/ ],
+  modules: [
+    {
+      name: "my-worker-script",
+      content_type: "application/javascript+module",
+      content_base64: Buffer.from(scriptContent).toString("base64"),
+    },
+  ],
+});
+
+/**
+ * Create a deployment and point all traffic to the version we created
+ */
+const deployment = await client.workers.scripts.deployments.create(worker.name, {
+  account_id: "...",
+  strategy: "percentage",
+  versions: [
+    {
+      percentage: 100,
+      version_id: version.id,
+    },
+  ],
+});
+```
+
+In Terraform, you now have the option to just manage the Worker entity. You don't need to manage code, config, or deployments in your plan. This gives you flexibility to use Wrangler for build and deploy while maintaining IaC presence.
+
+```tf
+resource "cloudflare_worker" "my_worker" {
+  account_id = "..."
+  name = "my-important-service"
+}
+
+# Manage these here or outside of Terraform
+# resource "cloudflare_workers_version" "my_worker_version" {}
+# resource "cloudflare_workers_deployment" "my_worker_deployment" {}
+```
+
+Check out [Infrastructure as Code (IaC)](/workers/platform/infrastructure-as-code) for more details and examples.

src/content/docs/workers/configuration/multipart-upload-metadata.mdx

@@ -5,6 +5,11 @@ title: Multipart upload metadata
 
 import { Type, MetaInfo } from "~/components";
 
+:::note
+
+There is a new API for uploading Workers. See [here](/workers/platform/infrastructure-as-code#cloudflare-rest-api) for more information.
+:::
+
 If you're using the [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/) or [Version Upload API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/) 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](/workers/wrangler/configuration/).
 
 ## Sample `metadata`

src/content/docs/workers/configuration/versions-and-deployments/index.mdx

@@ -69,6 +69,10 @@ When using [Wrangler](/workers/wrangler/), changes made to a Worker's triggers [
 New versions are not created when you make changes to [resources connected to your Worker](/workers/runtime-apis/bindings/). For example, if two Workers (Worker A and Worker B) are connected via a [service binding](/workers/runtime-apis/bindings/service-bindings/), changing the code of Worker B will not create a new version of Worker A. Changing the code of Worker B will only create a new version of Worker B. Changes to the service binding (such as, deleting the binding or updating the [environment](/workers/wrangler/environments/) it points to) on Worker A will also not create a new version of Worker B.
 :::
 
+#### Directly manage Versions and Deployments
+
+See examples of creating a Worker, Versions, and Deployments directly with the API, library SDKs, and Terraform in [Infrastructure as Code](/workers/platform/infrastructure-as-code/).
+
 ### View versions and deployments
 
 #### Via Wrangler

src/content/docs/workers/observability/logs/logpush.mdx

@@ -93,16 +93,6 @@ route = { pattern = "example.org/*", zone_name = "example.org" }
 
 </WranglerConfig>
 
-Configure via multipart script upload API:
-
-```bash
-curl --request PUT \
-"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}" \
---header "Authorization: Bearer <API_TOKEN>" \
---form 'metadata={"main_module": "my-worker.js", "logpush": true}' \
---form '"my-worker.js"=@./my-worker.js;type=application/javascript+module'
-```
-
 ## Limits
 
 The `logs` and `exceptions` fields have a combined limit of 16,384 characters before fields will start being truncated. Characters are counted in the order of all `exception.name`s, `exception.message`s, and then `log.message`s.