docs: require control data in create examples (#32)

* docs: require control data in create examples

* docs: fix python regex escaping in testing example

Author: lan17

components/server.mdx

@@ -173,7 +173,7 @@ GET /api/v1/agents/{agent_name}/controls
 ```bash
 # Create control
 PUT /api/v1/controls
-Body: { "name": "my-control" }
+Body: { "name": "my-control", "data": {...} }
 
 # List controls (cursor-based)
 GET /api/v1/controls?cursor=123&limit=100
@@ -188,7 +188,7 @@ Body: { "name": "new-name", "enabled": true }
 # Get control data
 GET /api/v1/controls/{control_id}/data
 
-# Update control data
+# Update existing control data
 PUT /api/v1/controls/{control_id}/data
 Body: { "data": {...} }
 

concepts/controls.mdx

@@ -429,17 +429,10 @@ Via curl:
 
 ```bash
 
-# Step 1: Create control
-
 CONTROL_ID=$(curl -X PUT http://localhost:8000/api/v1/controls \
-  -H "Content-Type: application/json" \
-  -d '{"name": "block-ssn-output"}' | jq -r '.control_id')
-
-# Step 2: Set control configuration
-
-curl -X PUT "http://localhost:8000/api/v1/controls/$CONTROL_ID/data" \
   -H "Content-Type: application/json" \
   -d '{
+    "name": "block-ssn-output",
     "data": {
       "description": "Block Social Security Numbers in responses",
       "enabled": true,
@@ -454,7 +447,7 @@ curl -X PUT "http://localhost:8000/api/v1/controls/$CONTROL_ID/data" \
       },
       "action": {"decision": "deny"}
     }
-  }'
+  }' | jq -r '.control_id')
 ```
 
 Regex pattern note: the pattern itself is `\b\d{3}-\d{2}-\d{4}\b`. Python raw strings render that as `r"\b\d{3}-\d{2}-\d{4}\b"`, while JSON payloads must escape backslashes as `"\\b\\d{3}-\\d{2}-\\d{4}\\b"`.
@@ -498,15 +491,10 @@ Via curl:
 
 ```bash
 
-# Create control with Luna-2 evaluator
-
 CONTROL_ID=$(curl -X PUT http://localhost:8000/api/v1/controls \
-  -H "Content-Type: application/json" \
-  -d '{"name": "block-toxic-input"}' | jq -r '.control_id')
-
-curl -X PUT "http://localhost:8000/api/v1/controls/$CONTROL_ID/data" \
   -H "Content-Type: application/json" \
   -d '{
+    "name": "block-toxic-input",
     "data": {
       "description": "Block toxic or harmful user messages",
       "enabled": true,
@@ -525,7 +513,7 @@ curl -X PUT "http://localhost:8000/api/v1/controls/$CONTROL_ID/data" \
       },
       "action": {"decision": "deny"}
     }
-  }'
+  }' | jq -r '.control_id')
 ```
 
 > **Note**: For the Luna-2 evaluator, set the `GALILEO_API_KEY` environment variable. See the [Evaluators](/concepts/evaluators/overview) for all available evaluators.

sdk/typescript-sdk.mdx

@@ -51,6 +51,24 @@ console.log(agents.agents.length);
 
 const created = await client.controls.create({
   name: "deny-pii",
+  data: {
+    action: { decision: "deny" },
+    description: "Block SSNs in output",
+    enabled: true,
+    evaluator: {
+      name: "regex",
+      config: {
+        pattern: "\\b\\d{3}-\\d{2}-\\d{4}\\b",
+      },
+    },
+    execution: "server",
+    scope: {
+      stages: ["post"],
+    },
+    selector: {
+      path: "output",
+    },
+  },
 });
 console.log(created.controlId);
 ```

testing.mdx

@@ -96,7 +96,23 @@ def test_scope_rejects_invalid_step_name_regex() -> None:
 ```python
 def test_create_control_returns_id(client: TestClient) -> None:
     # Given: a valid control payload
-    payload = {"name": "pii-protection"}
+    payload = {
+        "name": "pii-protection",
+        "data": {
+            "description": "Block SSNs in output",
+            "enabled": True,
+            "execution": "server",
+            "scope": {"stages": ["post"]},
+            "condition": {
+                "selector": {"path": "output"},
+                "evaluator": {
+                    "name": "regex",
+                    "config": {"pattern": r"\b\d{3}-\d{2}-\d{4}\b"},
+                },
+            },
+            "action": {"decision": "deny"},
+        },
+    }
 
     # When: creating the control via the public API
     response = client.put("/api/v1/controls", json=payload)