.datumproxy.net`). Create external CNAME or ALIAS records pointing at this hostname to route traffic through the platform. |
+| `status.conditions` | []Object | Current conditions of the HTTPProxy. |
+| `status.hostnameStatuses` | []Object | Per-hostname status for each configured hostname, including verification and DNS record programming conditions. Use this instead of the deprecated `hostnames` field for detailed per-hostname lifecycle information. |
+| `status.hostnames` | []string | Hostnames that have been bound to the HTTPProxy. Deprecated: use `hostnameStatuses` for detailed per-hostname status; this field will be removed in a future API version. |
+
+## Usage
+
+```yaml
+apiVersion: networking.datumapis.com/v1alpha
+kind: HTTPProxy
+metadata:
+ name: example-proxy
+spec:
+ hostnames:
+ - app.example.com
+ rules:
+ - name: default
+ backends:
+ - endpoint: https://backend.example.com
+```
+
+```bash
+datumctl apply -f httpproxy.yaml --project my-project
+datumctl get httpproxies --project my-project
+datumctl describe httpproxy example-proxy --project my-project
+```
+
+
+ Run `datumctl explain httpproxies --recursive` for the full, live field tree.
+
diff --git a/api/networking/network.mdx b/api/networking/network.mdx
new file mode 100644
index 0000000..4981bd7
--- /dev/null
+++ b/api/networking/network.mdx
@@ -0,0 +1,70 @@
+---
+title: "Network"
+sidebarTitle: "Network"
+description: "Network is the Schema for the networks API."
+---
+
+
+ API resource reference for **Network**, part of the [Networking service](/api/networking/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to read or inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ The `networking.datumapis.com/v1alpha` API is **alpha** and subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| **Group** | `networking.datumapis.com` |
+| **Version** | `v1alpha` |
+| **Kind** | `Network` |
+| **Scope** | Project |
+
+## Overview
+
+A Network defines a connectivity fabric within a Datum Cloud project. You use it to establish the IP addressing plan for your workloads — choosing which IP families are permitted, how addresses are allocated (IPAM), and the network MTU. Create a Network when you need a dedicated addressable space for the resources in a project.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.ipFamilies` | `[]string` | No | IP families to permit on a network. Defaults to IPv4. |
+| `spec.ipam` | `Object` | Yes | IPAM settings for the network. |
+| `spec.ipam.ipv4Range` | `string` | No | IPv4 range to use in auto mode networks. Defaults to `10.128.0.0/9`. |
+| `spec.ipam.ipv6Range` | `string` | No | IPv6 range to use in auto mode networks. Defaults to a `/48` allocated from `fd20::/20`. |
+| `spec.ipam.mode` | `string` | Yes | IPAM mode. One of `Auto`, `Policy`. |
+| `spec.mtu` | `integer` | No | Network MTU. May be between 1300 and 8856. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | `[]Object` | Represents the observations of a network's current state. |
+
+## Usage
+
+```yaml
+apiVersion: networking.datumapis.com/v1alpha
+kind: Network
+metadata:
+ name: my-network
+spec:
+ ipam:
+ mode: Auto
+```
+
+```bash
+# Apply the manifest
+datumctl apply -f network.yaml --project my-project
+
+# List networks in the project
+datumctl get networks --project my-project
+
+# Inspect a single network
+datumctl describe network my-network --project my-project
+```
+
+
+ Run `datumctl explain networks --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/networking/overview.mdx b/api/networking/overview.mdx
new file mode 100644
index 0000000..6e9d450
--- /dev/null
+++ b/api/networking/overview.mdx
@@ -0,0 +1,45 @@
+---
+title: "Networking"
+sidebarTitle: "Overview"
+description: "API reference for the networking.datumapis.com service — networks, subnets, HTTP proxies, and domains on Datum Cloud."
+---
+
+Datum Cloud networking lets you define and connect the infrastructure your applications run on. The `networking.datumapis.com` service groups the resources that describe your network topology and how traffic reaches your services: private [Networks](/api/networking/network) with their addressing, the [Subnets](/api/networking/subnet) carved out of them, [HTTPProxies](/api/networking/httpproxy) that expose services over HTTP, and the [Domains](/api/networking/domain) that name them. For fine-grained control over how service traffic is routed and secured, Datum Cloud also exposes the standard [Gateway API](/api/networking/gateway/overview) resources and the [Envoy Gateway](/api/networking/envoy/overview) extensions that build on them. You create and update these resources declaratively with `datumctl apply -f`, and inspect them with `datumctl get` and `datumctl describe`.
+
+
+ These resources are **alpha** (`v1alpha`). The API surface — fields, defaults, and behavior — may change in backward-incompatible ways between releases.
+
+
+## Piloted resources
+
+This reference documents a pilot subset of the networking service. More resources exist in `networking.datumapis.com`; the pages below cover the ones available in the pilot.
+
+
+
+ Define a private network with its IP families, address management, and MTU.
+
+
+ Carve an addressable range out of a network.
+
+
+ Expose a service over HTTP with a convenient reverse-proxy configuration.
+
+
+ Register a domain name in Datum for use by other networking resources.
+
+
+ Route service traffic with the open Gateway API standard — classes, gateways, routes, and backend TLS.
+
+
+ Extend the Gateway API with implementation-specific traffic and security policy.
+
+
+
+
+ New to editing Datum resources? See [Changing resources](/datumctl/resources/changing) for how to apply, edit, and safely preview changes with `datumctl`.
+
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Reading resources](/datumctl/resources/reading) — how to list, get, and inspect these resources with `datumctl`.
diff --git a/api/networking/subnet.mdx b/api/networking/subnet.mdx
new file mode 100644
index 0000000..e509a26
--- /dev/null
+++ b/api/networking/subnet.mdx
@@ -0,0 +1,82 @@
+---
+title: "Subnet"
+sidebarTitle: "Subnet"
+description: "Subnet is the Schema for the subnets API."
+---
+
+
+ API resource reference for **Subnet**, part of the [Networking service](/api/networking/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to read or inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of an **alpha** API (`v1alpha`). Its fields and behavior are subject to change.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| **Group** | `networking.datumapis.com` |
+| **Version** | `v1alpha` |
+| **Kind** | `Subnet` |
+| **Scope** | Project |
+
+## Overview
+
+A `Subnet` defines a range of IP addresses within a network context at a specific location. You create one to allocate addressing for a network, specifying the IP family, subnet class, start address, and prefix length. Once created, Datum Cloud tracks the subnet's allocated address range in its status.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.ipFamily` | string | Yes | The IP family of a subnet. One of `IPv4`, `IPv6`. |
+| `spec.location` | Object | Yes | The location which a subnet is associated with. |
+| `spec.location.name` | string | Yes | Name of a datum location. |
+| `spec.location.namespace` | string | Yes | Namespace for the datum location. |
+| `spec.networkContext` | Object | Yes | A subnet's network context. |
+| `spec.networkContext.name` | string | Yes | The network context name. |
+| `spec.prefixLength` | integer | Yes | The prefix length of a subnet. |
+| `spec.startAddress` | string | Yes | The start address of a subnet. |
+| `spec.subnetClass` | string | Yes | The class of subnet. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Represents the observations of a subnet's current state. |
+| `status.prefixLength` | integer | The prefix length of a subnet. |
+| `status.startAddress` | string | The start address of a subnet. |
+
+## Usage
+
+```yaml
+apiVersion: networking.datumapis.com/v1alpha
+kind: Subnet
+metadata:
+ name: my-subnet
+spec:
+ ipFamily: IPv4
+ subnetClass: private
+ startAddress: "10.0.0.0"
+ prefixLength: 24
+ location:
+ name: my-location
+ namespace: my-project
+ networkContext:
+ name: my-network-context
+```
+
+```bash
+# Create or update the subnet
+datumctl apply -f subnet.yaml --project my-project
+
+# List subnets in the project
+datumctl get subnets --project my-project
+
+# Inspect a single subnet
+datumctl describe subnet my-subnet --project my-project
+```
+
+
+ Run `datumctl explain subnets --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/contact.mdx b/api/notification/contact.mdx
new file mode 100644
index 0000000..fe0d1d2
--- /dev/null
+++ b/api/notification/contact.mdx
@@ -0,0 +1,74 @@
+---
+title: "Contact"
+sidebarTitle: "Contact"
+description: "Contact is the Schema for the contacts API. It represents a contact for a user."
+---
+
+
+ API resource reference for **Contact**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `Contact` |
+| Scope | Project |
+
+## Overview
+
+A `Contact` represents a person who can receive notifications from Datum Cloud, tied to a user subject. Use it to register the name and email address that Datum Cloud (and its downstream notification providers) should use when reaching out to a user within a Project.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.email` | string | Yes | The email address for the contact. |
+| `spec.givenName` | string | No | The contact's given (first) name. |
+| `spec.familyName` | string | No | The contact's family (last) name. |
+| `spec.subject` | Object | No | Reference to the subject the contact belongs to. |
+| `spec.subject.apiGroup` | string | Yes | API group of the referenced subject. Must be `iam.miloapis.com`. |
+| `spec.subject.kind` | string | Yes | Type of subject being referenced. Must be `User`. |
+| `spec.subject.name` | string | Yes | Name of the referenced subject. |
+| `spec.subject.namespace` | string | No | Namespace of the referenced subject. Required for Project-scoped subjects; omitted for Platform-scoped subjects. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the contact's state. The standard `Ready` condition tracks contact creation and sync to the contact provider. |
+| `status.providers` | []Object | Per-provider status for this contact, enabling multiple provider backends to be tracked simultaneously. |
+| `status.providerID` | string | Identifier returned by the underlying contact provider (e.g. Resend) when the contact is created. Deprecated: use `status.providers` instead. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: Contact
+metadata:
+ name: jane-doe
+spec:
+ email: jane.doe@example.com
+ givenName: Jane
+ familyName: Doe
+ subject:
+ apiGroup: iam.miloapis.com
+ kind: User
+ name: jane-doe
+```
+
+```bash
+datumctl apply -f contact.yaml --project my-project
+datumctl get contacts --project my-project
+datumctl describe contact jane-doe --project my-project
+```
+
+
+ Run `datumctl explain contacts --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/contactgroup.mdx b/api/notification/contactgroup.mdx
new file mode 100644
index 0000000..e8e31fb
--- /dev/null
+++ b/api/notification/contactgroup.mdx
@@ -0,0 +1,70 @@
+---
+title: "ContactGroup"
+sidebarTitle: "ContactGroup"
+description: "ContactGroup is the Schema for the contactgroups API. It represents a logical grouping of Contacts."
+---
+
+
+ API resource reference for **ContactGroup**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ContactGroup` |
+| Scope | Project |
+
+## Overview
+
+A `ContactGroup` represents a logical grouping of Contacts within a Project. Use it to organize the people who should receive notifications, and to control how members join or leave the group. A group can optionally be synced to an external email provider (such as Loops) so the same audience is available there.
+
+Visibility governs opt-out behavior: a `public` group lets members leave on their own (via a `ContactGroupMembershipRemoval`), while a `private` group enforces membership and rejects opt-out requests.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.displayName` | string | Yes | The display name of the contact group. |
+| `spec.visibility` | string | Yes | Whether members may opt in or out. One of `public` (members may leave via `ContactGroupMembershipRemoval`) or `private` (membership is enforced; opt-out requests are rejected). |
+| `spec.description` | string | No | Description of the contact group. Email providers (e.g. Loops) also use this on their generated opt-in/opt-out page. Synchronization of this field is not supported. |
+| `spec.providers` | []Object | No | The external providers this group should be synced to. |
+| `spec.providers[].name` | string | Yes | The provider handling this contact group. Allowed value: `Loops`. |
+| `spec.providers[].id` | string | Yes | The identifier of the contact group in the external provider. Used when a provider does not expose an API for creating mailing lists and requires an existing list ID (e.g. Loops); if omitted, a new group is created when the provider supports it. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the group's state. The standard `Ready` condition tracks group creation and sync to the provider. |
+| `status.providers` | []Object | Per-provider status, enabling tracking of multiple provider backends simultaneously. Each entry has `name` (`Resend` or `Loops`) and `id` (the identifier returned by that provider). |
+| `status.providerID` | string | Identifier returned by the underlying provider when the group is created. Deprecated: use `status.providers` instead. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: ContactGroup
+metadata:
+ name: platform-alerts
+spec:
+ displayName: Platform Alerts
+ visibility: public
+ description: Recipients for platform status and incident notifications.
+```
+
+```bash
+datumctl apply -f contactgroup.yaml --project my-project
+datumctl get contactgroups --project my-project
+datumctl describe contactgroup platform-alerts --project my-project
+```
+
+
+ Run `datumctl explain contactgroups --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/contactgroupmembership.mdx b/api/notification/contactgroupmembership.mdx
new file mode 100644
index 0000000..5a2c2f5
--- /dev/null
+++ b/api/notification/contactgroupmembership.mdx
@@ -0,0 +1,72 @@
+---
+title: "ContactGroupMembership"
+sidebarTitle: "ContactGroupMembership"
+description: "ContactGroupMembership is the Schema for the contactgroupmemberships API. It represents a membership of a Contact in a ContactGroup."
+---
+
+
+ API resource reference for **ContactGroupMembership**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ContactGroupMembership` |
+| Scope | Project |
+
+## Overview
+
+A `ContactGroupMembership` links a `Contact` to a `ContactGroup`, adding that contact as a member of the group. Use it when you want a contact to receive notifications sent to a group: create one membership per contact-to-group pairing. The membership references both the target `ContactGroup` and the `Contact` being added, and the controller tracks the sync of that membership to the underlying notification provider.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.contactGroupRef` | Object | Yes | Reference to the ContactGroup that the Contact is a member of. |
+| `spec.contactGroupRef.name` | string | Yes | Name of the ContactGroup being referenced. |
+| `spec.contactGroupRef.namespace` | string | Yes | Namespace of the ContactGroup being referenced. |
+| `spec.contactRef` | Object | Yes | Reference to the Contact that is a member of the ContactGroup. |
+| `spec.contactRef.name` | string | Yes | Name of the Contact being referenced. |
+| `spec.contactRef.namespace` | string | Yes | Namespace of the Contact being referenced. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the membership's state. The standard `Ready` condition tracks membership creation and sync to the contact group membership provider. |
+| `status.providers` | []Object | Per-provider status for this membership, enabling multiple provider backends to be tracked simultaneously. |
+| `status.providerID` | string | Identifier returned by the underlying contact provider (e.g. Resend) when the membership is created in the associated audience. Deprecated: use `status.providers` instead. |
+| `status.username` | string | Username of the user that owns the membership, populated by the controller from the referenced Contact's subject. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: ContactGroupMembership
+metadata:
+ name: alice-oncall
+spec:
+ contactGroupRef:
+ name: oncall
+ namespace: my-project
+ contactRef:
+ name: alice
+ namespace: my-project
+```
+
+```bash
+datumctl apply -f contactgroupmembership.yaml --project my-project
+datumctl get contactgroupmemberships --project my-project
+datumctl describe contactgroupmemberships alice-oncall --project my-project
+```
+
+
+ Run `datumctl explain contactgroupmemberships --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/email.mdx b/api/notification/email.mdx
new file mode 100644
index 0000000..a5fdbac
--- /dev/null
+++ b/api/notification/email.mdx
@@ -0,0 +1,80 @@
+---
+title: "Email"
+sidebarTitle: "Email"
+description: "Email is the Schema for the emails API."
+---
+
+
+ API resource reference for **Email**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `Email` |
+| Scope | Project |
+
+## Overview
+
+An `Email` represents a concrete message that Datum Cloud should send to a recipient. It references an `EmailTemplate` to render, names the recipient (either a `User` resource or a literal address), and supplies the variables needed to fill in the template. Use it to trigger a one-off notification e-mail within a Project; the platform renders the template, resolves the recipient, and delivers the message, recording the outcome in the resource status.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.templateRef` | Object | Yes | References the `EmailTemplate` that should be rendered. |
+| `spec.templateRef.name` | string | Yes | Name of the referenced `EmailTemplate`. |
+| `spec.recipient` | Object | Yes | The recipient of the e-mail. Provide exactly one of `userRef` or `emailAddress`. |
+| `spec.recipient.userRef` | Object | No | References the `User` resource that will receive the message. Mutually exclusive with `emailAddress`. |
+| `spec.recipient.userRef.name` | string | No | Name of the `User` resource that will receive the e-mail. Required when `userRef` is set. |
+| `spec.recipient.emailAddress` | string | No | Literal e-mail address for the recipient instead of a `User` reference. Mutually exclusive with `userRef`. |
+| `spec.variables` | []Object | No | Name/value pairs substituted into the template. Each entry requires `name` (as declared in the template) and `value`. |
+| `spec.priority` | string | No | Influences the order in which pending e-mails are processed. One of `low`, `normal`, `high`. |
+| `spec.cc` | []string | No | Additional addresses that receive a carbon copy. Maximum 10 addresses. |
+| `spec.bcc` | []string | No | Addresses that receive a blind-carbon copy. Maximum 10 addresses. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the e-mail's state; the standard `Delivered` condition tracks delivery. |
+| `status.emailAddress` | string | The final recipient address used for delivery, after resolving any referenced `User`. |
+| `status.subject` | string | The subject line used for the e-mail. |
+| `status.htmlBody` | string | The rendered HTML content of the e-mail. |
+| `status.textBody` | string | The rendered plain-text content of the e-mail. |
+| `status.providerID` | string | Identifier returned by the underlying e-mail provider when the message is accepted for delivery, used to track delivery status. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: Email
+metadata:
+ name: welcome-message
+spec:
+ templateRef:
+ name: welcome-template
+ recipient:
+ emailAddress: person@example.com
+ variables:
+ - name: firstName
+ value: Alex
+ priority: normal
+```
+
+```bash
+datumctl apply -f email.yaml --project my-project
+datumctl get emails --project my-project
+datumctl describe emails welcome-message --project my-project
+```
+
+
+ Run `datumctl explain emails --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/emailbroadcast.mdx b/api/notification/emailbroadcast.mdx
new file mode 100644
index 0000000..a9f5986
--- /dev/null
+++ b/api/notification/emailbroadcast.mdx
@@ -0,0 +1,74 @@
+---
+title: "EmailBroadcast"
+sidebarTitle: "EmailBroadcast"
+description: "EmailBroadcast is the Schema for the emailbroadcasts API. It represents a broadcast of an email to a set of contacts (ContactGroup)."
+---
+
+
+ API resource reference for **EmailBroadcast**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `EmailBroadcast` |
+| Scope | Project |
+
+## Overview
+
+An `EmailBroadcast` sends an email to every contact in a `ContactGroup`, rendering the message from a referenced `EmailTemplate`. Use it to deliver a one-time message — such as an announcement or notice — to a defined audience within a Project.
+
+A broadcast is immutable once created: if you need to change the message, schedule, or audience, delete the resource and create a new one. You can optionally defer delivery with `scheduledAt`; if omitted, the broadcast is sent as soon as the controller reconciles it.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.contactGroupRef` | Object | Yes | References the ContactGroup that the broadcast is sent to. |
+| `spec.contactGroupRef.name` | string | Yes | Name of the referenced ContactGroup. |
+| `spec.contactGroupRef.namespace` | string | Yes | Namespace of the referenced ContactGroup. |
+| `spec.templateRef` | Object | Yes | References the EmailTemplate used to render the message. With the Resend provider, `HTMLBody`/`TextBody` may include `{{{FIRST_NAME}}}`, `{{{LAST_NAME}}}`, and `{{{EMAIL}}}` placeholders that are substituted at send time. |
+| `spec.templateRef.name` | string | Yes | Name of the referenced EmailTemplate. |
+| `spec.displayName` | string | No | Human-friendly display name for the broadcast. |
+| `spec.scheduledAt` | string | No | Time at which the broadcast should be sent (e.g., `2024-08-05T11:52:01.858Z`). If omitted, the message is sent as soon as the resource is reconciled. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the broadcast's state. The standard `Ready` condition tracks send status and sync to the email provider. |
+| `status.providerID` | string | Identifier returned by the underlying email provider (e.g., Resend) when the broadcast is created; used to track send status via provider webhooks. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: EmailBroadcast
+metadata:
+ name: launch-announcement
+spec:
+ displayName: Launch Announcement
+ contactGroupRef:
+ name: newsletter-subscribers
+ namespace: my-project
+ templateRef:
+ name: launch-announcement-template
+ scheduledAt: "2024-08-05T11:52:01.858Z"
+```
+
+```bash
+datumctl apply -f emailbroadcast.yaml --project my-project
+datumctl get emailbroadcasts --project my-project
+datumctl describe emailbroadcast launch-announcement --project my-project
+```
+
+
+ Run `datumctl explain emailbroadcasts --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/emailtemplate.mdx b/api/notification/emailtemplate.mdx
new file mode 100644
index 0000000..61e407e
--- /dev/null
+++ b/api/notification/emailtemplate.mdx
@@ -0,0 +1,78 @@
+---
+title: "EmailTemplate"
+sidebarTitle: "EmailTemplate"
+description: "EmailTemplate is the Schema for the email templates API. It represents a reusable e-mail template that can be rendered by substituting the declared variables."
+---
+
+
+ **Platform-provided resource.** Datum operates this resource; you typically reference or read it rather than create it. See [Platform resources](/api/platform/overview).
+
+
+
+ API resource reference for **EmailTemplate**. See [Platform resources](/api/platform/overview) for related platform-provided resources. To read or inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `notification.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `EmailTemplate` |
+| Scope | Platform |
+
+## Overview
+
+An `EmailTemplate` is a reusable e-mail template that Datum Cloud renders when it needs to send a notification. The template defines a subject line along with HTML and plain-text bodies written as Go template strings, and it enumerates the variables that callers are expected to provide when the message is rendered. Use it to standardize the wording and formatting of notification e-mails so the same content can be produced consistently by substituting the declared variables at send time.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.subject` | string | Yes | The string that composes the email subject line. |
+| `spec.htmlBody` | string | Yes | The string for the HTML representation of the message. |
+| `spec.textBody` | string | Yes | The Go template string for the plain-text representation of the message. |
+| `spec.variables` | []Object | No | Enumerates all variables that can be referenced inside the template expressions. |
+| `spec.variables[].name` | string | Yes | The identifier of the variable as it appears inside the Go template (e.g. `{{.UserName}}`). |
+| `spec.variables[].required` | boolean | Yes | Whether the variable must be provided when rendering the template. |
+| `spec.variables[].type` | string | Yes | A hint about the expected value of this variable. One of `string` or `url`. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest available observations of the template's current state, indicating whether it is ready for use. |
+
+## Usage
+
+```yaml
+apiVersion: notification.miloapis.com/v1alpha1
+kind: EmailTemplate
+metadata:
+ name: welcome-email
+spec:
+ subject: "Welcome to Datum Cloud, {{.UserName}}"
+ htmlBody: "Hello {{.UserName}}, visit your dashboard to get started.
"
+ textBody: "Hello {{.UserName}}, visit {{.DashboardURL}} to get started."
+ variables:
+ - name: UserName
+ required: true
+ type: string
+ - name: DashboardURL
+ required: true
+ type: url
+```
+
+```bash
+datumctl apply -f emailtemplate.yaml
+datumctl get emailtemplates
+datumctl describe emailtemplate welcome-email
+```
+
+
+ Run `datumctl explain emailtemplates --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/notification/overview.mdx b/api/notification/overview.mdx
new file mode 100644
index 0000000..29be56f
--- /dev/null
+++ b/api/notification/overview.mdx
@@ -0,0 +1,38 @@
+---
+title: "Notification"
+sidebarTitle: "Overview"
+description: "Contacts, contact groups, and email delivery on Datum Cloud — the notification.miloapis.com service."
+---
+
+Datum Cloud manages notification recipients and email delivery through the `notification.miloapis.com` API. You declare the people you contact, organize them into reusable groups, and send email — either one message or a broadcast to a group, optionally rendered from a shared template. Contacts, groups, memberships, and email resources are all created with `datumctl apply -f` and read with `datumctl get` and `datumctl describe`.
+
+
+ The Notification API is **alpha** (`v1alpha1`). Fields and behavior may change in backward-incompatible ways between releases.
+
+
+## Resources
+
+
+
+ A single notification recipient, including their email address and identifying details.
+
+
+ A named, reusable group of contacts you can target as a broadcast audience.
+
+
+ Associates a contact with a contact group.
+
+
+ A single email message sent to a recipient.
+
+
+ An email sent to every contact in a contact group.
+
+
+
+**Platform-provided:** the [EmailTemplate](/api/notification/emailtemplate) used to render an email lives under [Platform resources](/api/platform/overview).
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Changing resources](/datumctl/resources/changing) — how to apply, edit, and safely preview changes to these resources.
diff --git a/api/overview.mdx b/api/overview.mdx
new file mode 100644
index 0000000..c438995
--- /dev/null
+++ b/api/overview.mdx
@@ -0,0 +1,121 @@
+---
+title: "API resources"
+sidebarTitle: "Overview"
+description: "The resource and field reference for Datum Cloud services."
+---
+
+This section is the **resource and field reference** for Datum Cloud. It documents the resources each service exposes and the fields you set and read on them — what a resource *is*, not how to accomplish a task with it.
+
+
+ Looking for how-to guides instead? Here's how the references fit together:
+
+ - **API resources** (you are here) — the resource/field reference: what fields a resource has, their types, and what they mean.
+ - **[datumctl](/datumctl/overview)** — task-oriented how-to guides for using the CLI. Run `datumctl --help` for the command and flag reference.
+
+
+
+ The Datum Cloud API is currently **alpha** (`v1alpha`/`v1alpha1`). Resources, fields, and defaults may change in backward-incompatible ways between releases.
+
+
+## Start with the concepts
+
+Every Datum Cloud resource shares the same shape and workflow, so a handful of ideas apply to *all* of them. Read these first and the per-service pages become quick lookups rather than fresh material each time.
+
+
+
+ The declarative model behind every resource — `apiVersion`, `kind`, `metadata`, `spec`, and `status`. Start here.
+
+
+ The shared `metadata` block: names, labels, annotations, and the fields the platform manages for you.
+
+
+ How to read observed state and the standard `conditions` pattern to tell whether a resource is ready.
+
+
+ Whether a resource lives inside a **Project** or is shared across the **Platform**, and how that maps to your context.
+
+
+
+
+ Three more concept pages round out the shared model: [versioning & stability](/api/concepts/versioning), [resource references](/api/concepts/references), [field formats & types](/api/concepts/field-formats), and [validation & safe changes](/api/concepts/validation).
+
+
+## Browse by service
+
+Resources are organized by the service that owns them. Services group into three layers: **Foundation** services model who you are and what you own, **Infrastructure** services run and connect your workloads, and **Operations** services govern consumption, billing, and communication.
+
+### Foundation
+
+Model your organizations, projects, access control, and machine identities.
+
+
+
+ Organizations, projects, and the membership that ties people to them.
+
+
+ Roles, policy bindings, groups, service accounts, and user invitations that control access.
+
+
+
+### Infrastructure
+
+Run workloads and connect them to the network.
+
+
+
+ Workloads, deployments, and the instances that run them.
+
+
+ Networks, subnets, gateways, and HTTP routing resources.
+
+
+ Managed DNS zones and records for your domains.
+
+
+ IP pools, claims, and allocations for address management.
+
+
+
+### Operations
+
+Govern consumption, pay for what you use, and stay informed.
+
+
+
+ Allowance buckets, resource claims, and grants that meter usage.
+
+
+ Billing accounts, account bindings, and payment methods.
+
+
+ Export policies that ship metrics and logs to your own tooling.
+
+
+ Contacts, contact groups, and the emails and broadcasts sent to them.
+
+
+
+
+ **[Platform resources](/api/platform/overview)** collects the platform-provided and reference resources you point at rather than compose — the service catalog (Services, entitlements, and consumers), classes like `DNSZoneClass` and `GatewayClass`, `IPPool`s that claims allocate from, and email templates.
+
+
+## How to read these pages
+
+Each resource page follows the same structure, and each part is explained in depth on its concept page:
+
+- **Identity** — the resource's kind, [API group and version](/api/concepts/versioning), and [scope](/api/concepts/scopes) (**Project** or **Platform**).
+- **Spec fields** — the fields you set to declare desired state. See [API conventions](/api/concepts/conventions) for the `spec`/`status` model, [field formats & types](/api/concepts/field-formats) for how the `Type` and `Required` columns read, and [object metadata](/api/concepts/metadata) for the shared `metadata` block every page omits.
+- **Status** — the read-only fields the platform reports back, including the shared [status & conditions](/api/concepts/status-and-conditions) pattern. Fields that point at other resources follow the [resource references](/api/concepts/references) convention.
+- **Usage** — how to create, read, and inspect the resource with `datumctl`.
+
+Manifests are applied with `datumctl apply -f`, and you can read or inspect resources with `datumctl get` and `datumctl describe` — see [changing resources](/datumctl/resources/changing) and [reading resources](/datumctl/resources/reading). Every write is checked first; see [validation & safe changes](/api/concepts/validation).
+
+```bash
+datumctl apply -f my-resource.yaml
+datumctl get
+datumctl describe
+```
+
+
+ Field types and required markers throughout this reference come straight from the live API schema, which you can also explore from the CLI with `datumctl explain`.
+
diff --git a/api/platform/overview.mdx b/api/platform/overview.mdx
new file mode 100644
index 0000000..6dc8dc8
--- /dev/null
+++ b/api/platform/overview.mdx
@@ -0,0 +1,58 @@
+---
+title: "Platform resources"
+sidebarTitle: "Overview"
+description: "Platform-provided and reference resources — the service catalog, classes and pools other resources point at, and email templates you read or reference rather than create."
+---
+
+This section collects Datum Cloud's **platform-provided and reference resources**: things Datum operates or publishes that you typically **read or reference** rather than create. They include the service catalog, the classes that other resources point at (such as a DNS zone class or a gateway class), the address pools that back IP allocation, and the email templates that shape platform notifications.
+
+These differ from the resources you create and manage day to day inside a Project — networks, DNS zones, gateways, workloads, and the like. Those are documented across the rest of the reference; see the [API resources overview](/api/overview) for the full picture. The pages below describe the shared, upstream pieces you consume: you reference a class by name, opt in to a service, or draw addresses from a pool, but the resource itself is provided for you.
+
+
+ These APIs are currently **alpha** (`v1alpha`/`v1alpha1`). Resources, fields, and defaults may change in backward-incompatible ways between releases.
+
+
+## Service catalog
+
+The catalog of managed capabilities Datum offers, the entitlements you create to use them, and the consumer records providers see.
+
+
+
+ The platform-owned identity record for a managed capability, keyed by its canonical `serviceName`.
+
+
+ Created in your Project to opt in to a service; one per service you want to use.
+
+
+ The provider's view of an entitlement, reflected into the provider Project for approval and tracking.
+
+
+
+## Reference classes & pools
+
+Classes and pools are provided by the platform and referenced by name from the resources you create — pick a class or pool, and Datum supplies the implementation behind it.
+
+
+
+ The class a DNS zone references to select how the platform hosts and serves it.
+
+
+ The class a gateway references to select its platform-provided implementation.
+
+
+ The address pools that back IP claims and allocations in your Project.
+
+
+
+## Templates
+
+
+
+ The reusable email content the platform renders when it sends notifications.
+
+
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Scopes](/api/concepts/scopes) — whether a resource lives inside a **Project** or is shared across the **Platform**.
diff --git a/api/quota/allowancebucket.mdx b/api/quota/allowancebucket.mdx
new file mode 100644
index 0000000..2b3429a
--- /dev/null
+++ b/api/quota/allowancebucket.mdx
@@ -0,0 +1,79 @@
+---
+title: "AllowanceBucket"
+sidebarTitle: "AllowanceBucket"
+description: "AllowanceBucket aggregates quota limits and usage for a single (consumer, resourceType) combination."
+---
+
+
+ API resource reference for **AllowanceBucket**, part of the [Quota service](/api/quota/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `quota.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `AllowanceBucket` |
+| Scope | Project |
+
+## Overview
+
+An `AllowanceBucket` aggregates quota capacity and consumption for a single (consumer, resource type) pair. The quota system creates one bucket automatically for each unique combination found in active `ResourceGrant` resources, then continuously tallies the total granted capacity (`limit`) against the amount consumed by granted `ResourceClaim` resources (`allocated`) to compute what remains (`available`).
+
+You typically do not create buckets by hand — they are system-managed and read-mostly. You use them to see how much quota a consumer has, how much is in use, and how much is left, which drives real-time admission decisions when new `ResourceClaim` resources are created.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.consumerRef` | Object | Yes | Identifies the quota consumer this bucket tracks. Must match the consumer on the `ResourceGrant` resources that contribute to the bucket. |
+| `spec.consumerRef.kind` | string | Yes | Type of consumer resource, e.g. `Organization`, `Project`, or `User`. |
+| `spec.consumerRef.name` | string | Yes | Name of the specific consumer instance, e.g. `acme-corp`. |
+| `spec.consumerRef.apiGroup` | string | No | API group of the consumer resource, e.g. `resourcemanager.miloapis.com`. |
+| `spec.consumerRef.namespace` | string | No | Namespace of the consumer resource; required for Project-scoped consumers, left empty for Organization-scoped consumers. |
+| `spec.resourceType` | string | Yes | The resource type this bucket aggregates quota for. Must match a registered `ResourceRegistration` resource type, e.g. `resourcemanager.miloapis.com/projects`. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.limit` | integer | Total quota capacity for this (consumer, resource type), summed from all active contributing `ResourceGrant` resources. |
+| `status.allocated` | integer | Total quota currently consumed by granted `ResourceClaim` resources. |
+| `status.available` | integer | Remaining capacity, computed as `limit - allocated` (never negative); drives admission decisions. |
+| `status.claimCount` | integer | Number of granted `ResourceClaim` resources consuming from this bucket. |
+| `status.grantCount` | integer | Number of active `ResourceGrant` resources contributing to this bucket's limit. |
+| `status.contributingGrantRefs` | []Object | Per-grant detail (`name`, `amount`, `lastObservedGeneration`) for each `ResourceGrant` that contributes capacity. |
+| `status.lastReconciliation` | string | Timestamp of the last recalculation; indicates how fresh the aggregated data is. |
+| `status.observedGeneration` | integer | Most recent spec generation the quota system has processed. |
+
+## Usage
+
+Buckets are normally created automatically, but the spec is small enough to inspect or reproduce directly:
+
+```yaml
+apiVersion: quota.miloapis.com/v1alpha1
+kind: AllowanceBucket
+metadata:
+ name: acme-corp-projects
+spec:
+ consumerRef:
+ apiGroup: resourcemanager.miloapis.com
+ kind: Organization
+ name: acme-corp
+ resourceType: resourcemanager.miloapis.com/projects
+```
+
+```bash
+datumctl apply -f allowancebucket.yaml --project my-project
+datumctl get allowancebuckets --project my-project
+datumctl describe allowancebuckets acme-corp-projects --project my-project
+```
+
+
+ Run `datumctl explain allowancebuckets --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/quota/overview.mdx b/api/quota/overview.mdx
new file mode 100644
index 0000000..60710d6
--- /dev/null
+++ b/api/quota/overview.mdx
@@ -0,0 +1,40 @@
+---
+title: "Quota"
+sidebarTitle: "Overview"
+description: "Resource allowances, claims, and grants that govern usage on Datum Cloud — the quota.miloapis.com API."
+---
+
+Datum Cloud governs how much of each resource type a consumer may use through the `quota.miloapis.com` API. Capacity is allocated to a consumer with a **ResourceGrant**, individual requests draw against that capacity with a **ResourceClaim**, and an **AllowanceBucket** continuously aggregates the two to report how much remains available for admission decisions.
+
+
+ The quota API is **alpha** (`v1alpha1`). Fields and behavior may change in backward-incompatible ways between releases.
+
+
+## Resources
+
+
+
+ Aggregates quota limits and usage for a single consumer and resource type, reporting the capacity still available.
+
+
+ Requests quota allocation when a resource is created, consuming capacity from the matching bucket.
+
+
+ Allocates quota capacity to a consumer for specific resource types, supplying the allowances buckets aggregate.
+
+
+
+## How the pieces fit together
+
+- A **ResourceGrant** grants a consumer capacity for one or more resource types. Only grants with an `Active` status contribute to available quota.
+- An **AllowanceBucket** is created automatically for each unique consumer and resource type. It sums capacity from active grants and consumption from granted claims, then reports the remaining `status.available`.
+- A **ResourceClaim** requests an allocation for a resource type. The quota system checks the matching bucket's available capacity to decide whether the claim can be granted.
+
+
+ Inspect the exact fields for any resource with `datumctl explain`, for example `datumctl explain allowancebuckets.spec` or `datumctl explain resourceclaims.spec`.
+
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Changing resources](/datumctl/resources/changing) — how to apply, edit, and safely preview changes to these resources.
diff --git a/api/quota/resourceclaim.mdx b/api/quota/resourceclaim.mdx
new file mode 100644
index 0000000..c5d5750
--- /dev/null
+++ b/api/quota/resourceclaim.mdx
@@ -0,0 +1,97 @@
+---
+title: "ResourceClaim"
+sidebarTitle: "ResourceClaim"
+description: "ResourceClaim requests quota allocation during resource creation, consuming quota capacity from AllowanceBuckets."
+---
+
+
+ API resource reference for **ResourceClaim**, part of the [Quota service](/api/quota/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `quota.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ResourceClaim` |
+| Scope | Project |
+
+## Overview
+
+A `ResourceClaim` requests quota allocation when a resource is created. Each claim consumes quota capacity from the matching `AllowanceBucket` and links back to the resource that triggered it, so quota usage can be tracked, audited, and cleaned up over its lifecycle.
+
+Most claims are created automatically by a `ClaimCreationPolicy` during admission, but administrators can also create them by hand for testing or special allocation scenarios. All requests in a single claim are evaluated atomically: either every request has sufficient quota and the whole claim is granted, or any shortage denies the entire claim. Once granted, a claim reserves the requested amounts until it is deleted.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.requests` | []Object | Yes | The resource types and amounts being claimed. Minimum 1, maximum 20 requests per claim; each resource type may appear only once. Processed atomically. |
+| `spec.requests[].resourceType` | string | Yes | Identifies the resource type being claimed. Must exactly match an active `ResourceRegistration.spec.resourceType` (e.g. `resourcemanager.miloapis.com/projects`, `compute_cpu`). |
+| `spec.requests[].amount` | integer | Yes | How much quota to claim, measured in the BaseUnit from the `ResourceRegistration`. Use `1` for single instances (Entity registrations) or a capacity value for Allocation registrations. |
+| `spec.consumerRef` | Object | No | Identifies the quota consumer making the claim. Can be omitted when created via `ClaimCreationPolicy` (auto-filled from the authenticated context). |
+| `spec.consumerRef.kind` | string | Yes* | Type of consumer resource (e.g. `Organization`, `Project`, `User`). Required when `consumerRef` is set. |
+| `spec.consumerRef.name` | string | Yes* | Name of the specific consumer instance. Required when `consumerRef` is set. |
+| `spec.consumerRef.apiGroup` | string | No | API group of the consumer resource (e.g. `resourcemanager.miloapis.com`, `iam.miloapis.com`). |
+| `spec.consumerRef.namespace` | string | No | Scope of the consumer resource. Required for Project-scoped consumers (e.g. Projects); empty for Platform-scoped consumers (e.g. Organizations). |
+| `spec.resourceRef` | Object | No | Identifies the resource that triggered this claim. Auto-populated by `ClaimCreationPolicy` during admission. |
+| `spec.resourceRef.kind` | string | Yes* | Type of the referenced resource (e.g. `Project`, `User`, `Organization`). Required when `resourceRef` is set. |
+| `spec.resourceRef.name` | string | Yes* | Name of the specific triggering resource instance. Required when `resourceRef` is set. |
+| `spec.resourceRef.apiGroup` | string | No | API group of the referenced resource (e.g. `resourcemanager.miloapis.com`). |
+| `spec.resourceRef.namespace` | string | No | Scope containing the referenced resource. Required for Project-scoped resources, omitted for Platform-scoped ones. |
+
+
+ Fields marked Yes* are required only when their parent object (`consumerRef` or `resourceRef`) is present.
+
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Overall claim evaluation status. The `Granted` condition indicates approval, with reasons such as `QuotaAvailable`, `QuotaExceeded`, `ValidationFailed`, or `PendingEvaluation`. |
+| `status.allocations` | []Object | Per-request allocation detail, one entry per `spec.requests` item, indexed by resource type. |
+| `status.allocations[].resourceType` | string | Which request this allocation describes; matches a `spec.requests[].resourceType`. |
+| `status.allocations[].status` | string | Allocation result for this request: `Granted`, `Denied`, or `Pending`. |
+| `status.allocations[].allocatedAmount` | integer | How much quota was allocated. Equals the requested amount when granted, `0` when denied or pending. |
+| `status.allocations[].allocatingBucket` | string | Name of the `AllowanceBucket` that provided the quota. Set only when granted. |
+| `status.allocations[].reason` | string | Machine-readable status reason (e.g. `QuotaAvailable`, `QuotaExceeded`, `ValidationFailed`). |
+| `status.allocations[].message` | string | Human-readable explanation of the allocation result. |
+| `status.allocations[].lastTransitionTime` | string | When this allocation status last changed. |
+| `status.observedGeneration` | integer | Most recent spec generation the system has processed. |
+
+## Usage
+
+```yaml
+apiVersion: quota.miloapis.com/v1alpha1
+kind: ResourceClaim
+metadata:
+ name: web-app-project-claim
+spec:
+ consumerRef:
+ apiGroup: resourcemanager.miloapis.com
+ kind: Organization
+ name: acme-corp
+ resourceRef:
+ apiGroup: resourcemanager.miloapis.com
+ kind: Project
+ name: web-app-project
+ namespace: acme-corp
+ requests:
+ - resourceType: resourcemanager.miloapis.com/projects
+ amount: 1
+```
+
+```bash
+datumctl apply -f resourceclaim.yaml --project my-project
+datumctl get resourceclaims --project my-project
+datumctl describe resourceclaim web-app-project-claim --project my-project
+```
+
+
+ Run `datumctl explain resourceclaims --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/quota/resourcegrant.mdx b/api/quota/resourcegrant.mdx
new file mode 100644
index 0000000..ca5499d
--- /dev/null
+++ b/api/quota/resourcegrant.mdx
@@ -0,0 +1,79 @@
+---
+title: "ResourceGrant"
+sidebarTitle: "ResourceGrant"
+description: "ResourceGrant allocates quota capacity to a consumer for specific resource types."
+---
+
+
+ API resource reference for **ResourceGrant**, part of the [Quota service](/api/quota/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `quota.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ResourceGrant` |
+| Scope | Project |
+
+## Overview
+
+A `ResourceGrant` allocates quota capacity to a consumer (such as an Organization, Project, or User) for one or more resource types. Each grant lists the allowances it provides, and the quota system aggregates capacity from all active grants into allowance buckets that resource claims then draw against.
+
+Use a `ResourceGrant` to hand out quota: define base allocations for a consumer, add extra capacity for a specific tier, or express incremental increases over time. Grants can be created directly by an administrator or generated automatically by a policy. When the quota system validates a grant successfully, it marks the grant `Active` and its allowances begin contributing to quota decisions; grants that fail validation do not contribute until corrected.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.allowances` | []Object | Yes | The quota allocations provided by this grant. Minimum 1, maximum 20 allowances. All allowances share the same consumer and activate or deactivate together with the grant. |
+| `spec.allowances[].resourceType` | string | Yes | Identifies the resource type receiving the allocation. Must exactly match the resource type of an active `ResourceRegistration` (e.g. `resourcemanager.miloapis.com/projects`, `compute_cpu`, `storage.volumes`). |
+| `spec.allowances[].buckets` | []Object | Yes | Individual allocations for this resource type. All bucket amounts are summed to determine the total allowance. Minimum 1 bucket required. |
+| `spec.allowances[].buckets[].amount` | integer | Yes | Capacity provided by this bucket, measured in the BaseUnit of the corresponding `ResourceRegistration`. Must be a non-negative integer (0 is valid but provides no quota). |
+| `spec.consumerRef` | Object | Yes | Identifies the quota consumer that receives these allowances. The consumer type must match the consumer type expected by each allowance's `ResourceRegistration`. |
+| `spec.consumerRef.kind` | string | Yes | Type of consumer resource, such as `Organization`, `Project`, or `User`. |
+| `spec.consumerRef.name` | string | Yes | Name of the specific consumer resource instance (e.g. `acme-corp`, `web-application`). |
+| `spec.consumerRef.apiGroup` | string | No | API group of the consumer resource (e.g. `resourcemanager.miloapis.com`, `iam.miloapis.com`). |
+| `spec.consumerRef.namespace` | string | No | Scope of the consumer resource. Set for Project-scoped consumers; leave empty for Platform-scoped consumers such as Organizations. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest observations of the grant's state. The `Active` condition indicates whether the grant is validated and contributing capacity to allowance buckets; when `False`, the condition message reports the validation error. |
+| `status.observedGeneration` | integer | The most recent spec generation the quota system has processed. When it matches `metadata.generation`, the status reflects the current spec; a lower value means changes are still being processed. |
+
+## Usage
+
+```yaml
+apiVersion: quota.miloapis.com/v1alpha1
+kind: ResourceGrant
+metadata:
+ name: acme-corp-project-quota
+spec:
+ consumerRef:
+ apiGroup: resourcemanager.miloapis.com
+ kind: Organization
+ name: acme-corp
+ allowances:
+ - resourceType: resourcemanager.miloapis.com/projects
+ buckets:
+ - amount: 100
+```
+
+```bash
+datumctl apply -f resourcegrant.yaml --project my-project
+datumctl get resourcegrants --project my-project
+datumctl describe resourcegrant acme-corp-project-quota --project my-project
+```
+
+
+ Run `datumctl explain resourcegrants --recursive` to see the full, live field tree for this resource.
+
+
+
diff --git a/api/resource-manager/organization.mdx b/api/resource-manager/organization.mdx
new file mode 100644
index 0000000..14ffcb7
--- /dev/null
+++ b/api/resource-manager/organization.mdx
@@ -0,0 +1,60 @@
+---
+title: "Organization"
+sidebarTitle: "Organization"
+description: "Organization is the Schema for the Organizations API."
+---
+
+
+ API resource reference for **Organization**, part of the [Resource Manager service](/api/resource-manager/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `resourcemanager.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `Organization` |
+| Scope | Platform |
+
+## Overview
+
+An `Organization` is the top-level container in Datum Cloud that owns projects, members, and billing. Because it is Platform-scoped, it exists across the whole platform rather than inside a single project. Use it to establish an organizational boundary — either a `Personal` organization tied to an individual account, or a `Standard` organization for a team or company.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.type` | string | Yes | The type of organization. One of `Personal` or `Standard`. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Observations of the organization's current state. Known condition types include `Ready`. |
+| `status.observedGeneration` | integer | The most recent generation observed for this Organization by the controller. |
+
+## Usage
+
+```yaml
+apiVersion: resourcemanager.miloapis.com/v1alpha1
+kind: Organization
+metadata:
+ name: acme
+spec:
+ type: Standard
+```
+
+```bash
+datumctl apply -f organization.yaml
+datumctl get organizations
+datumctl describe organization acme
+```
+
+
+ Run `datumctl explain organizations --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/resource-manager/organizationmembership.mdx b/api/resource-manager/organizationmembership.mdx
new file mode 100644
index 0000000..b54670b
--- /dev/null
+++ b/api/resource-manager/organizationmembership.mdx
@@ -0,0 +1,77 @@
+---
+title: "OrganizationMembership"
+sidebarTitle: "OrganizationMembership"
+description: "OrganizationMembership establishes a user's membership in an organization and optionally assigns roles to grant permissions."
+---
+
+
+ API resource reference for **OrganizationMembership**, part of the [Resource Manager service](/api/resource-manager/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `resourcemanager.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `OrganizationMembership` |
+| Scope | Project |
+
+## Overview
+
+An `OrganizationMembership` connects a user to an organization and, optionally, grants that user one or more roles within it. Creating a membership establishes the user-organization relationship; listing roles on the membership grants the corresponding permissions.
+
+Use it whenever you want to add someone to an organization or adjust what they can do there. When you assign roles, the controller automatically creates and manages the underlying `PolicyBinding` resources for each role, so you manage access in one place. Roles can be added or removed at any time after the membership exists. The referenced user, organization, and roles must already exist before you create the membership.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.organizationRef` | Object | Yes | Identifies the organization to grant membership in. The organization must exist beforehand. |
+| `spec.organizationRef.name` | string | Yes | Name of the referenced organization. |
+| `spec.userRef` | Object | Yes | Identifies the user to grant organization membership. The user must exist beforehand. |
+| `spec.userRef.name` | string | Yes | Name of the referenced user. |
+| `spec.roles` | []Object | No | List of roles to assign to the user within the organization. Omit or leave empty to establish membership with no roles. Duplicate roles are rejected. |
+| `spec.roles[].name` | string | Yes | Name of the referenced role. |
+| `spec.roles[].namespace` | string | No | Location of the referenced role. Defaults to the membership's own location if not set. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.appliedRoles` | []Object | Per-role reconciliation state for each entry in `spec.roles`. Each entry records `name`, `namespace`, `status` (`Applied`, `Pending`, or `Failed`), a `policyBindingRef` and `appliedAt` timestamp when applied, and a `message` explaining failures. |
+| `status.conditions` | []Object | Tracks state such as `Ready` (membership established) and `RolesApplied` (whether all roles were successfully applied). |
+| `status.observedGeneration` | integer | The most recent membership spec generation the controller has processed. |
+| `status.organization` | Object | Cached information about the referenced organization, populated by the controller. |
+| `status.user` | Object | Cached information about the referenced user, populated by the controller. |
+
+## Usage
+
+```yaml
+apiVersion: resourcemanager.miloapis.com/v1alpha1
+kind: OrganizationMembership
+metadata:
+ name: jane-acme-membership
+spec:
+ organizationRef:
+ name: acme-corp
+ userRef:
+ name: jane-doe
+ roles:
+ - name: organization-viewer
+ namespace: organization-acme-corp
+```
+
+```bash
+datumctl apply -f organizationmembership.yaml --project my-project
+datumctl get organizationmemberships --project my-project
+datumctl describe organizationmembership jane-acme-membership --project my-project
+```
+
+
+ Run `datumctl explain organizationmemberships --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/resource-manager/overview.mdx b/api/resource-manager/overview.mdx
new file mode 100644
index 0000000..d90735a
--- /dev/null
+++ b/api/resource-manager/overview.mdx
@@ -0,0 +1,30 @@
+---
+title: "Resource Manager"
+sidebarTitle: "Overview"
+description: "Organizations and projects — the top-level containers for everything you run on Datum Cloud."
+---
+
+Datum Cloud groups everything you build under the `resourcemanager.miloapis.com` API. An **Organization** is the top-level container that owns billing, membership, and access; a **Project** lives within an organization and holds the resources you actually run — DNS zones, networks, and more. **OrganizationMembership** connects a user to an organization and assigns the roles that grant them access. Together these form the container hierarchy that every other Datum Cloud resource lives inside.
+
+
+ The Resource Manager API is **alpha** (`v1alpha1`). Fields and behavior may change in backward-incompatible ways between releases.
+
+
+## Resources
+
+
+
+ The top-level container that owns billing, membership, and access for everything beneath it.
+
+
+ A container within an organization that holds the resources you run on Datum Cloud.
+
+
+ Connects a user to an organization and assigns the roles that grant them access.
+
+
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Changing resources](/datumctl/resources/changing) — how to apply, edit, and safely preview changes to these resources.
diff --git a/api/resource-manager/project.mdx b/api/resource-manager/project.mdx
new file mode 100644
index 0000000..c6ace4d
--- /dev/null
+++ b/api/resource-manager/project.mdx
@@ -0,0 +1,63 @@
+---
+title: "Project"
+sidebarTitle: "Project"
+description: "Project is the Schema for the projects API."
+---
+
+
+ API resource reference for **Project**, part of the [Resource Manager service](/api/resource-manager/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `resourcemanager.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `Project` |
+| Scope | Platform |
+
+## Overview
+
+A `Project` is a top-level container that groups related Datum Cloud resources — such as DNS zones, networking, and other workloads — under a single owning organization. Most Project-scoped resources live inside a Project, and you select one with the `--project` flag when reading or applying manifests. Use a Project to organize resources by team, environment, or application, all owned by an `Organization`.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.ownerRef` | Object | Yes | Reference to the owner of the project. Must be a valid resource. |
+| `spec.ownerRef.kind` | string | Yes | Kind of the owning resource. Must be `Organization`. |
+| `spec.ownerRef.name` | string | Yes | Name of the owning resource. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Observations of the project's current state. Known condition types include `Ready`. |
+
+## Usage
+
+```yaml
+apiVersion: resourcemanager.miloapis.com/v1alpha1
+kind: Project
+metadata:
+ name: my-project
+spec:
+ ownerRef:
+ kind: Organization
+ name: my-organization
+```
+
+```bash
+datumctl apply -f project.yaml
+datumctl get projects
+datumctl describe project my-project
+```
+
+
+ Run `datumctl explain projects --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/services/service.mdx b/api/services/service.mdx
new file mode 100644
index 0000000..23c98d4
--- /dev/null
+++ b/api/services/service.mdx
@@ -0,0 +1,83 @@
+---
+title: "Service"
+sidebarTitle: "Service"
+description: "Service is the Schema for the services API. It is the platform-owned identity record for a managed service offered on Datum."
+---
+
+
+ **Platform-provided resource.** Datum operates this resource; you typically reference or read it rather than create it. See [Platform resources](/api/platform/overview).
+
+
+
+ API resource reference for **Service**, part of the platform service catalog. See [Platform resources](/api/platform/overview) for the full catalog. To read or inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `services.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `Service` |
+| Scope | Platform |
+
+## Overview
+
+A `Service` is the platform-owned identity record for a managed capability a provider offers on Datum Cloud. It holds everything consumer-facing: the canonical name, display name, description, owning producer project, and lifecycle phase. Runtime concerns such as deployments, images, endpoints, and routing stay in the provider's own repository; this resource is identity only.
+
+The canonical identifier is `spec.serviceName`, a reverse-DNS name (for example, `compute.miloapis.com`) that appears on invoices, in the portal, and in every downstream reference. Once a service is Published, `serviceName` is locked: breaking changes ship as a new `Service` with a new `serviceName` and a coordinated migration rather than a silent mutation. Use a `Service` to register a capability so downstream governance resources (such as MeterDefinition and MonitoredResourceType) and consumers (quota, marketplace, entitlements) can reference it.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.serviceName` | string | Yes | Canonical reverse-DNS identifier (e.g., `compute.miloapis.com`). The cross-system join key used by billing exports and the portal. Immutable. |
+| `spec.displayName` | string | Yes | Human-readable name surfaced in the portal, marketplace, and on invoices. Editable over the service's lifetime. |
+| `spec.phase` | string | Yes | Provider-declared lifecycle state. Forward-only transitions: `Draft` → `Published` → `Deprecated` → `Retired`. |
+| `spec.owner` | Object | Yes | Identifies the producer project that publishes and owns the service. |
+| `spec.owner.producerProjectRef` | Object | Yes | Reference to the producer-project resource that owns the service. |
+| `spec.owner.producerProjectRef.name` | string | Yes | The `metadata.name` of the owning producer-project resource. |
+| `spec.description` | string | No | Plain-English explanation of what the service offers. Editable over the service's lifetime. |
+| `spec.enablementPolicy` | Object | No | Controls whether consumers can self-service enable the service or must wait for provider approval. |
+| `spec.enablementPolicy.mode` | string | Yes (within object) | Selects the enablement flow for this service. |
+| `spec.dependencies` | []Object | No | Services that must be enabled alongside this service; the platform auto-enables any listed dependency not already active in a consumer's project. |
+| `spec.dependencies[].serviceRef` | Object | Yes (within object) | Identifies the dependent service. |
+| `spec.dependencies[].serviceRef.name` | string | Yes (within object) | The `metadata.name` of the dependent service. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Latest available observations of the resource's state, including how the controller reflects the declared phase. |
+| `status.observedGeneration` | integer | The most recent generation observed by the controller. |
+| `status.publishedAt` | string | Time at which the controller first observed the resource in the Published phase; preserved across later transitions to Deprecated and Retired. |
+
+## Usage
+
+```yaml
+apiVersion: services.miloapis.com/v1alpha1
+kind: Service
+metadata:
+ name: compute
+spec:
+ serviceName: compute.miloapis.com
+ displayName: Compute
+ phase: Draft
+ owner:
+ producerProjectRef:
+ name: my-producer-project
+```
+
+```bash
+datumctl apply -f service.yaml --project my-project
+datumctl get services.services.miloapis.com --project my-project
+datumctl describe services.services.miloapis.com compute --project my-project
+```
+
+
+ Run `datumctl explain services.services.miloapis.com --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/services/serviceconsumer.mdx b/api/services/serviceconsumer.mdx
new file mode 100644
index 0000000..041da8b
--- /dev/null
+++ b/api/services/serviceconsumer.mdx
@@ -0,0 +1,83 @@
+---
+title: "ServiceConsumer"
+sidebarTitle: "ServiceConsumer"
+description: "ServiceConsumer is the Schema for the serviceconsumers API."
+---
+
+
+ **Platform-provided resource.** Datum operates this resource; you typically reference or read it rather than create it. See [Platform resources](/api/platform/overview).
+
+
+
+ API resource reference for **ServiceConsumer**, part of the platform service catalog. See [Platform resources](/api/platform/overview) for the full catalog. To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `services.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ServiceConsumer` |
+| Scope | Platform |
+
+## Overview
+
+A `ServiceConsumer` is the record that links a consumer project to a service it has requested access to. The services controller creates one `ServiceConsumer` in the provider project's control plane for every active or pending service entitlement, so providers never create these directly.
+
+Instead, providers use this resource to act on access requests for `GatedByProvider` services: they write the `spec.approval` field to approve or deny a request. The controller reflects the outcome in the status, tracking whether the consumer record is pending approval, active, or denied.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.consumerProjectRef` | Object | Yes | Identifies the consumer project that requested access to the service. |
+| `spec.consumerProjectRef.name` | string | Yes | Name of the consumer project. |
+| `spec.serviceRef` | Object | Yes | Identifies the Service this consumer record is associated with. |
+| `spec.serviceRef.name` | string | Yes | Name of the referenced Service. |
+| `spec.approval` | Object | No | The provider's decision for `GatedByProvider` services. The controller creates the object; the provider writes only this field. |
+| `spec.approval.decision` | string | No | The provider's approval or denial of the consumer request. Required when `spec.approval` is set. |
+| `spec.approval.message` | string | No | An optional human-readable explanation of the decision. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.phase` | string | Controller-observed lifecycle state of the consumer record: `PendingApproval`, `Active`, or `Denied`. |
+| `status.serviceName` | string | The canonical service identifier (e.g. `compute.datumapis.com`) resolved from `spec.serviceRef` and set by the controller. |
+| `status.entitledAt` | string | The time at which this consumer record became `Active`. |
+| `status.conditions` | []Object | Latest available observations of the consumer record's state. |
+| `status.observedGeneration` | integer | The most recent generation observed by the controller. |
+
+## Usage
+
+Because the controller creates the `ServiceConsumer`, providers typically edit an existing record to record an approval decision rather than applying a new one:
+
+```yaml
+apiVersion: services.miloapis.com/v1alpha1
+kind: ServiceConsumer
+metadata:
+ name: acme-compute-consumer
+spec:
+ consumerProjectRef:
+ name: acme-project
+ serviceRef:
+ name: compute
+ approval:
+ decision: Approved
+ message: Approved for production compute access.
+```
+
+```bash
+datumctl apply -f serviceconsumer.yaml
+datumctl get serviceconsumers
+datumctl describe serviceconsumer acme-compute-consumer
+```
+
+
+ Run `datumctl explain serviceconsumers --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/services/serviceentitlement.mdx b/api/services/serviceentitlement.mdx
new file mode 100644
index 0000000..61020ef
--- /dev/null
+++ b/api/services/serviceentitlement.mdx
@@ -0,0 +1,75 @@
+---
+title: "ServiceEntitlement"
+sidebarTitle: "ServiceEntitlement"
+description: "ServiceEntitlement is the Schema for the serviceentitlements API."
+---
+
+
+ **Platform-provided resource.** Datum operates this resource; you typically reference or read it rather than create it. See [Platform resources](/api/platform/overview).
+
+
+
+ API resource reference for **ServiceEntitlement**, part of the platform service catalog. See [Platform resources](/api/platform/overview) for the full catalog. To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `services.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ServiceEntitlement` |
+| Scope | Platform |
+
+## Overview
+
+A `ServiceEntitlement` records a consumer project's intent to use a specific Datum Cloud service. A project admin creates one `ServiceEntitlement` per service they want to enable. The object is written into the consumer project's control plane, and the services operator reconciles it into the provider project so the requested service becomes available.
+
+Some services require provider approval before they become active; for those, you can include a human-readable message with your request. Entitlements can also be created automatically when one service depends on another.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.serviceRef` | Object | Yes | Identifies the Service the consumer project wants to enable. |
+| `spec.serviceRef.name` | string | Yes | The name of the referenced Service. |
+| `spec.requestMessage` | string | No | Optional human-readable message sent to the provider when the service requires approval. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.phase` | string | Controller-observed lifecycle state: `PendingApproval`, `Active`, or `Rejected`. |
+| `status.origin` | string | Whether this entitlement was created directly by a consumer admin (`Direct`) or automatically as a dependency of another entitlement (`Dependency`). |
+| `status.serviceName` | string | Canonical service identifier resolved from `spec.serviceRef` (e.g., `compute.datumapis.com`), set by the controller on first successful reconcile. |
+| `status.entitledAt` | string | The time at which this entitlement became Active. |
+| `status.dependencyOf` | string | The `metadata.name` of the ServiceEntitlement that caused this entitlement to be created when origin is `Dependency`. |
+| `status.observedGeneration` | integer | The most recent generation observed by the controller. |
+| `status.conditions` | []Object | Latest available observations of the entitlement's state. |
+
+## Usage
+
+```yaml
+apiVersion: services.miloapis.com/v1alpha1
+kind: ServiceEntitlement
+metadata:
+ name: compute-datumapis-com
+spec:
+ serviceRef:
+ name: compute.datumapis.com
+ requestMessage: "Enabling compute for the production workloads project."
+```
+
+```bash
+datumctl apply -f serviceentitlement.yaml --project my-project
+datumctl get serviceentitlements --project my-project
+datumctl describe serviceentitlement compute-datumapis-com --project my-project
+```
+
+
+ Run `datumctl explain serviceentitlements --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/telemetry/exportpolicy.mdx b/api/telemetry/exportpolicy.mdx
new file mode 100644
index 0000000..388f46c
--- /dev/null
+++ b/api/telemetry/exportpolicy.mdx
@@ -0,0 +1,84 @@
+---
+title: "ExportPolicy"
+sidebarTitle: "ExportPolicy"
+description: "ExportPolicy is the Schema for the export policy API."
+---
+
+
+ API resource reference for **ExportPolicy**, part of the [Telemetry service](/api/telemetry/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+
+
+
+ This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `telemetry.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `ExportPolicy` |
+| Scope | Project |
+
+## Overview
+
+An `ExportPolicy` sends telemetry data collected on the Datum Cloud platform to a third-party telemetry platform. You define one or more **sources** that select which telemetry data to publish, and one or more **sinks** that describe where to send it and how to authenticate. Each sink references the sources it should forward.
+
+Use an `ExportPolicy` when you want your platform metrics to land in an external observability system, for example by pushing them to an endpoint that speaks the Prometheus Remote Write protocol. The control plane continuously evaluates the deployed exporters and reconciles them to match the policy. Note that delivery is not guaranteed, especially when a sink's endpoint is unavailable, and telemetry matching multiple sources is not de-duplicated.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.sources` | []Object | Yes | The telemetry sources to publish to the configured sinks. Multiple sources may be defined; matching data is not de-duplicated across sources. |
+| `spec.sources[].name` | string | Yes | A unique name for the source within the policy. Must be a valid DNS label. |
+| `spec.sources[].metrics` | Object | No | Selects metric data to retrieve from the Datum Cloud platform. |
+| `spec.sources[].metrics.metricsql` | string | No | A MetricSQL query used to select and filter metric data to publish (e.g. `{service_name="networking.miloapis.com", resource_kind="Gateway"}`). See the [MetricSQL reference](https://docs.victoriametrics.com/metricsql/). |
+| `spec.sinks` | []Object | Yes | How telemetry data should be sent to third-party platforms. |
+| `spec.sinks[].name` | string | Yes | A name for the sink that is unique within the policy. |
+| `spec.sinks[].sources` | []string | Yes | The names of the sources whose data should be sent to this sink. |
+| `spec.sinks[].target` | Object | Yes | The target the sink delivers telemetry to. |
+| `spec.sinks[].target.prometheusRemoteWrite` | Object | No | Publishes telemetry using the Prometheus Remote Write protocol. |
+| `spec.sinks[].target.prometheusRemoteWrite.endpoint` | string | Yes | The HTTP endpoint to publish telemetry data to. |
+| `spec.sinks[].target.prometheusRemoteWrite.authentication` | Object | No | How the sink authenticates with the endpoint (e.g. `basicAuth`). |
+| `spec.sinks[].target.prometheusRemoteWrite.batch` | Object | Yes | How telemetry is batched before sending. Defaults to every 5 seconds or 500 entries, whichever comes first. |
+| `spec.sinks[].target.prometheusRemoteWrite.retry` | Object | Yes | Retry behavior when requests to the endpoint fail. Retries are not guaranteed to succeed if the endpoint is unavailable or misconfigured. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Summary status for the policy as a whole. Known condition types: `Ready`. |
+| `status.sinks` | []Object | Per-sink status information for each configured sink. |
+
+## Usage
+
+```yaml
+apiVersion: telemetry.miloapis.com/v1alpha1
+kind: ExportPolicy
+metadata:
+ name: gateway-metrics
+spec:
+ sources:
+ - name: gateway-metrics
+ metrics:
+ metricsql: '{service_name="networking.miloapis.com", resource_kind="Gateway"}'
+ sinks:
+ - name: prometheus
+ sources:
+ - gateway-metrics
+ target:
+ prometheusRemoteWrite:
+ endpoint: https://metrics.example.com/api/v1/write
+```
+
+```bash
+datumctl apply -f exportpolicy.yaml --project my-project
+datumctl get exportpolicies --project my-project
+datumctl describe exportpolicy gateway-metrics --project my-project
+```
+
+
+ Run `datumctl explain exportpolicies --recursive` to see the full, live field tree for this resource.
+
diff --git a/api/telemetry/overview.mdx b/api/telemetry/overview.mdx
new file mode 100644
index 0000000..1f50d55
--- /dev/null
+++ b/api/telemetry/overview.mdx
@@ -0,0 +1,24 @@
+---
+title: "Telemetry"
+sidebarTitle: "Overview"
+description: "Telemetry export configuration on Datum Cloud — declare where your metrics, logs, and traces are sent."
+---
+
+Datum Cloud provides telemetry export configuration through the `telemetry.miloapis.com` API. You declare where telemetry collected from your resources should be sent, and Datum handles delivering it to the configured destination. Export configuration is a Project resource you create with `datumctl apply -f`.
+
+
+ The Telemetry API is **alpha** (`v1alpha1`). Fields and behavior may change in backward-incompatible ways between releases.
+
+
+## Resources
+
+
+
+ Configures how telemetry is exported from a Project to an external destination.
+
+
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Changing resources](/datumctl/resources/changing) — how to apply, edit, and safely preview changes to these resources.
diff --git a/docs.json b/docs.json
index deb6af9..d8005da 100644
--- a/docs.json
+++ b/docs.json
@@ -219,6 +219,155 @@
]
}
]
+ },
+ {
+ "tab": "API resources",
+ "icon": "boxes-stacked",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": [
+ "api/overview"
+ ]
+ },
+ {
+ "group": "Concepts",
+ "pages": [
+ "api/concepts/conventions",
+ "api/concepts/metadata",
+ "api/concepts/status-and-conditions",
+ "api/concepts/scopes",
+ "api/concepts/versioning",
+ "api/concepts/references",
+ "api/concepts/field-formats",
+ "api/concepts/validation"
+ ]
+ },
+ {
+ "group": "Resource Manager",
+ "pages": [
+ "api/resource-manager/overview",
+ "api/resource-manager/organization",
+ "api/resource-manager/project",
+ "api/resource-manager/organizationmembership"
+ ]
+ },
+ {
+ "group": "IAM",
+ "pages": [
+ "api/iam/overview",
+ "api/iam/role",
+ "api/iam/policybinding",
+ "api/iam/group",
+ "api/iam/groupmembership",
+ "api/iam/serviceaccount",
+ "api/iam/userinvitation"
+ ]
+ },
+ {
+ "group": "Compute",
+ "pages": [
+ "api/compute/overview",
+ "api/compute/workload",
+ "api/compute/workloaddeployment",
+ "api/compute/instance"
+ ]
+ },
+ {
+ "group": "Networking",
+ "pages": [
+ "api/networking/overview",
+ "api/networking/network",
+ "api/networking/subnet",
+ "api/networking/httpproxy",
+ "api/networking/domain",
+ {
+ "group": "Gateway API",
+ "pages": [
+ "api/networking/gateway/overview",
+ "api/networking/gateway/gateway",
+ "api/networking/gateway/httproute",
+ "api/networking/gateway/backendtlspolicy"
+ ]
+ },
+ {
+ "group": "Envoy Gateway",
+ "pages": [
+ "api/networking/envoy/overview",
+ "api/networking/envoy/backend",
+ "api/networking/envoy/backendtrafficpolicy",
+ "api/networking/envoy/httproutefilter",
+ "api/networking/envoy/securitypolicy"
+ ]
+ }
+ ]
+ },
+ {
+ "group": "DNS",
+ "pages": [
+ "api/dns/overview",
+ "api/dns/dnszone",
+ "api/dns/dnsrecordset"
+ ]
+ },
+ {
+ "group": "IPAM",
+ "pages": [
+ "api/ipam/overview",
+ "api/ipam/ipclaim",
+ "api/ipam/ipallocation"
+ ]
+ },
+ {
+ "group": "Quota",
+ "pages": [
+ "api/quota/overview",
+ "api/quota/allowancebucket",
+ "api/quota/resourceclaim",
+ "api/quota/resourcegrant"
+ ]
+ },
+ {
+ "group": "Billing",
+ "pages": [
+ "api/billing/overview",
+ "api/billing/billingaccount",
+ "api/billing/billingaccountbinding",
+ "api/billing/paymentmethod"
+ ]
+ },
+ {
+ "group": "Telemetry",
+ "pages": [
+ "api/telemetry/overview",
+ "api/telemetry/exportpolicy"
+ ]
+ },
+ {
+ "group": "Notification",
+ "pages": [
+ "api/notification/overview",
+ "api/notification/contact",
+ "api/notification/contactgroup",
+ "api/notification/contactgroupmembership",
+ "api/notification/email",
+ "api/notification/emailbroadcast"
+ ]
+ },
+ {
+ "group": "Platform resources",
+ "pages": [
+ "api/platform/overview",
+ "api/services/service",
+ "api/services/serviceentitlement",
+ "api/services/serviceconsumer",
+ "api/dns/dnszoneclass",
+ "api/networking/gateway/gatewayclass",
+ "api/ipam/ippool",
+ "api/notification/emailtemplate"
+ ]
+ }
+ ]
}
]
},
@@ -299,4 +448,4 @@
"prefill": false
}
}
-}
\ No newline at end of file
+}