diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx
index 77404dd..b667fdb 100644
--- a/api-reference/agents.mdx
+++ b/api-reference/agents.mdx
@@ -561,9 +561,11 @@ The request is proxied to the backend provisioning service. A dedicated Mux live
 | `aiProvider` | string | No | AI provider (default: `openrouter`). Options: `openrouter`, `gemini`, `groq`, `anthropic`, `openai` |
 | `apiKey` | string | No | API key for the AI provider |
 | `plan` | string | No | Plan tier. Options: `solo`, `collective`, `label`, `network`. A paid plan is required — requests with `plan` set to `free` (or omitted) return `402 Payment Required`. |
-| `email` | string | No | User email address. Used for admin and tester bypass of payment enforcement. |
+| `email` | string | No | User email address. Used for admin and tester bypass of payment enforcement. Falls back to the `x-user-email` request header when not provided in the body (see below). |
 | `stripeSubscriptionId` | string | No | Active Stripe subscription ID. Required for non-admin, non-tester users on paid plans. When absent and the user is not an admin or tester, the endpoint returns `402 Payment Required`. |
 
+<Note>The `email` field can also be provided via the `x-user-email` request header. When the request body does not include `email`, the backend reads the header value instead. This is useful when the auth middleware has already resolved the user's email and forwarded it in the header.</Note>
+
 <Warning>The `free` plan value is deprecated. The provisioning service now requires a paid plan (`solo`, `collective`, `label`, or `network`) and a valid Stripe subscription. Requests with `plan` set to `free` return `402 Payment Required` with `code: "PAYMENT_REQUIRED"`.</Warning>
 
 <Warning>The following request fields are deprecated and no longer accepted: `whatsappPhoneNumberId`, `whatsappBusinessAccountId`, `discordGuildId`, `discordChannelId`.</Warning>
@@ -642,6 +644,7 @@ When calling the backend provisioning service directly, the response includes ad
 | 429 | Too many requests |
 | 500 | Internal server error |
 | 502 | Provisioning service unavailable or returned an error |
+| 503 | Provisioning is temporarily disabled (kill switch active) |
 
 ## Agent interaction