From 58d6257203e61bd6ef26bc1852965d509537d473 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 20 Mar 2026 22:52:10 +0000
Subject: [PATCH] Document x-user-email header fallback and 503 kill switch
 error for provision endpoint

Generated-By: mintlify-agent
---
 api-reference/agents.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

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