[K2] Add K2 documentation (#33858)

* Add K2 documentation

* AI feedback

* Add CODEOWNERS

* re-run CI

---------

Co-authored-by: Marc Selwan <marc@marcinthecloud.com>

Author: mwylde

.github/CODEOWNERS

@@ -521,6 +521,14 @@ package.json @cloudflare/content-engineering
 /src/content/release-notes/images.yaml @deannalam @dochne @renandincer @third774 @cloudflare/product-owners
 /src/icons/images.svg @deannalam @dochne @renandincer @third774 @cloudflare/product-owners
 
+# k2
+
+/src/content/docs/k2/ @Marcinthecloud @mwylde @sejoker @cloudflare/product-owners
+/src/assets/images/k2/ @Marcinthecloud @mwylde @sejoker @cloudflare/product-owners
+/src/content/changelog/k2/ @Marcinthecloud @mwylde @sejoker @cloudflare/pm-changelogs @cloudflare/product-owners
+/src/content/directory/k2.yaml @Marcinthecloud @mwylde @sejoker @cloudflare/product-owners
+/src/icons/k2.svg @Marcinthecloud @mwylde @sejoker @cloudflare/product-owners
+
 # key-transparency
 
 /src/content/docs/key-transparency/ @lschull @mgalicer @cloudflare/appsec-reviewers @cloudflare/product-owners

src/components/landing/BuildFromScratch.astro

@@ -72,6 +72,7 @@ const primitives = [
 		tags: [
 			{ label: "R2", href: "/r2/" },
 			{ label: "Basin", href: "/basin/" },
+			{ label: "K2", href: "/k2/" },
 			{ label: "D1", href: "/d1/" },
 			{ label: "KV", href: "/kv/" },
 			{ label: "Hyperdrive", href: "/hyperdrive/" },

src/components/landing/sidebar-data.ts

@@ -128,6 +128,7 @@ export const sidebarSections: SidebarSection[] = [
 							link("Basin SQL", "/basin-sql/"),
 						],
 					},
+					link("K2", "/k2/"),
 					link("D1", "/d1/"),
 					link("KV", "/kv/"),
 					link("Hyperdrive", "/hyperdrive/"),

src/content/directory/k2.yaml

@@ -0,0 +1,13 @@
+id: FKFjPd
+name: K2
+
+entry:
+  title: K2
+  url: /k2/
+  group: Developer platform
+  additional_groups: [Storage]
+
+meta:
+  title: Cloudflare K2 docs
+  description: A durable event stream
+  author: "@cloudflare"

src/content/docs/k2/concepts/index.mdx

@@ -0,0 +1,75 @@
+---
+title: Concepts
+description: Learn about the key ideas behind K2, including streams, records, subscriptions, and leases.
+pcx_content_type: concept
+products:
+  - k2
+sidebar:
+  order: 3
+---
+
+This page introduces the concepts underlying K2.
+
+## Streams
+
+The core primitive in K2 is what we call a _stream_ — an ordered, durable, log of
+events. The stream sits between producers writing events and consumers
+reading them. Unlike a traditional queue, where consumption removes items,
+production and consumption in a log are completely decoupled. Writes append
+events to the log, while reads merely advance a pointer (or _offset_)
+within the log.
+
+This has some useful properties:
+
+- Writes and reads are completely independent, so we never run out of
+  space or otherwise block writes due to slow reads
+- We can support multiple independent readers consuming the entire stream
+  (pub-sub style) as readers do not affect each other or the log
+- We can support historical replay, as data is only removed based on a configurable
+  time-to-live (TTL)
+
+Each stream has a name and a retention period. When you create a stream, K2 assigns it a unique ID,
+which producers and consumers use to communicate with it. Producers write to a stream through
+an HTTP endpoint (with or without authentication), a Workers binding, or both.
+
+## Records
+
+Records are the data written to a stream. Each record has the following fields:
+
+- `content`: a binary message, containing arbitrary data; base64-encoded in the HTTP APIs
+- `headers`: an optional map of string keys to string values that can be used to describe the data in the content
+
+Headers are useful for describing the content, without needing to deserialize it. Common use
+cases for headers include:
+
+- Storing the encoding, so the reader knows how to deserialize the content
+- Representing data used to route or filter events, improving efficiency by avoiding deserialization
+  when not necessary
+- Annotating content in a pass-through pipeline without needing to modify the underlying data
+
+Records can be up to 1 MB, counting across both content and headers.
+
+## Subscriptions
+
+Reads from K2 are performed via _subscriptions_. Each subscription will receive all messages
+in the stream, and multiple consumers can share a single subscription.
+
+This enables K2 to support two delivery strategies: reads can be shared amongst
+a set of consumers (such that each consumer gets a subset of the messages), or
+delivered to all consumers independently (such that each consumer gets all
+messages). These strategies can also be mixed, with multiple groups of
+consumers which each get a subset of the messages.
+
+Subscriptions are created with an initial position in the log: either `earliest`, which receives
+all retained (not deleted according to the TTL) data in the stream, or `latest` which receives
+all events from the time the subscription is created.
+
+## Leases
+
+Once a subscription is created, clients can consume from it by POSTing to the subscription's
+`/consume` endpoint. This returns a list of messages which this client is expected to process.
+These messages are _leased_ to that client for a particular amount of time — the _lease period_,
+which is 5 minutes. The client is expected, before the lease expires, to either _ack_ the messages,
+telling the subscription that they are successfully consumed, or _nack_ them, indicating a processing
+failure. Events owned by a nack'd or timed-out lease will be redelivered on a subsequent call to
+consume.

src/content/docs/k2/configuration/index.mdx

@@ -0,0 +1,125 @@
+---
+title: Configuration
+description: Create, update, and delete K2 streams, and configure their inputs, authentication, CORS, and retention.
+pcx_content_type: configuration
+products:
+  - k2
+sidebar:
+  order: 5
+---
+
+import { Details } from "~/components";
+
+K2 streams can be created, updated, and deleted with the REST API.
+
+To create, update, or delete streams, your API token needs the `K2 Config Write` permission. To get or list streams, it needs the `K2 Config Read` permission.
+
+{/* TODO: Add Dashboard and Wrangler instructions once they support K2 streams. */}
+
+## Stream settings
+
+| Setting             | Type    | Required | Default             | Description                                                                                     |
+| ------------------- | ------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------- |
+| `name`              | string  | Yes      | None                | 1 to 128 letters, numbers, or underscores. Must be unique in your account. Not case-sensitive.  |
+| `retention_seconds` | integer | No       | `604800`            | How long K2 retains records, from `3600` (one hour) to `2592000` (30 days).                     |
+| `http`              | object  | Yes      | None                | Configures the HTTP input. Refer to [HTTP input](#http-input).                                  |
+| `worker_binding`    | object  | No       | `{ enabled: true }` | Configures the Workers binding input. Refer to [Workers binding input](#workers-binding-input). |
+
+At least one of `http` or `worker_binding` must be enabled.
+
+You cannot rename a stream after you create it.
+
+### Inputs
+
+An input is a way for producers to write records to a stream. K2 supports two inputs:
+
+- **HTTP:** Producers send records to the stream's `/produce` endpoint.
+- **Workers binding:** A Worker sends records through a binding.
+
+### HTTP input
+
+| Field            | Type             | Required | Description                                                                                                                            |
+| ---------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`        | boolean          | Yes      | Enables the `/produce` endpoint.                                                                                                       |
+| `authentication` | boolean          | No       | Requires an API token with the `K2 Produce` permission to produce. If omitted or `false`, anyone with the stream endpoint can produce. |
+| `cors.origins`   | array of strings | No       | Origins allowed to produce from a browser. Refer to [CORS](#cors).                                                                     |
+
+:::caution
+If you do not set `authentication` to `true`, the `/produce` endpoint is public. Anyone who knows the stream ID can write records to the stream.
+:::
+
+#### Authentication
+
+When `authentication` is `true`, producers using the HTTP API must send an API token in the
+`Authorization: Bearer <TOKEN>` header. The token must have permission to
+produce to K2 streams (`K2 Produce`) in the account that owns the stream.
+
+#### CORS
+
+Configure `cors.origins` to allow browsers to produce records from a web page. Each entry must be one of the following:
+
+- An `http://` or `https://` origin, such as `https://example.com`. Origins cannot include a path, query string, fragment, or credentials.
+- `*`, to allow any origin. If you use `*`, it must be the only entry.
+
+You can configure up to five origins. Each origin must be unique.
+
+### Workers binding input
+
+| Field     | Type    | Required | Description                                             |
+| --------- | ------- | -------- | ------------------------------------------------------- |
+| `enabled` | boolean | Yes      | Allows Workers to produce to the stream with a binding. |
+
+If you omit `worker_binding` when you create a stream, the Workers binding input is enabled.
+
+### Retention
+
+`retention_seconds` sets how long K2 retains records after it receives them.
+The value must be between `3600` (one hour) and `2592000` (30 days). The
+default is `604800` (seven days).
+
+K2 deletes expired records in the background. Records can remain readable for some time after their retention period ends, so do not rely on retention to remove data at an exact time.
+
+## Update a stream
+
+To change a stream's settings, send a `PATCH` request with the settings to change. You can update `retention_seconds`, `http`, and `worker_binding`. Include at least one of these fields.
+
+```sh
+curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/k2/streams/$STREAM_ID" \
+  --request PATCH \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "retention_seconds": 86400,
+    "worker_binding": { "enabled": false }
+  }'
+```
+
+The response contains the updated stream:
+
+```json output
+{
+	"success": true,
+	"errors": [],
+	"messages": [],
+	"result": {
+		"id": "241fa65b438a4d539a19371f58bfdae0",
+		"name": "orders",
+		"retention_seconds": 86400,
+		"endpoint": "https://241fa65b438a4d539a19371f58bfdae0.k2.cloudflarestorage.com",
+		"http": {
+			"enabled": true,
+			"authentication": true
+		},
+		"worker_binding": {
+			"enabled": false
+		},
+		"created_at": "2026-09-24T21:19:19.246Z",
+		"modified_at": "2026-09-29T14:25:54.712Z"
+	}
+}
+```
+
+When you update an input, the new object replaces the existing one. For
+example, to add a CORS origin to the HTTP input, send the complete `http`
+object, including `enabled` and `authentication`. To disable an input, set it
+to `{ "enabled": false }`. You cannot disable both inputs.