simstudioai
diff --git a/‎apps/docs/content/docs/yaml/blocks/api.mdx‎
Lines changed: 290 additions & 38 deletions b/‎apps/docs/content/docs/yaml/blocks/api.mdx‎
Lines changed: 290 additions & 38 deletions
@@ -33,30 +33,54 @@ properties:
         enum: [GET, POST, PUT, DELETE, PATCH]
         description: HTTP method for the request
         default: GET
-      queryParams:
+      params:
         type: array
-        description: Query parameters as key-value pairs
+        description: Query parameters as table entries
         items:
           type: object
+          required:
+            - id
+            - cells
           properties:
-            key:
+            id:
               type: string
-              description: Parameter name
-            value:
-              type: string
-              description: Parameter value
+              description: Unique identifier for the parameter entry
+            cells:
+              type: object
+              required:
+                - Key
+                - Value
+              properties:
+                Key:
+                  type: string
+                  description: Parameter name
+                Value:
+                  type: string
+                  description: Parameter value
       headers:
         type: array
-        description: HTTP headers as key-value pairs
+        description: HTTP headers as table entries
         items:
           type: object
+          required:
+            - id
+            - cells
           properties:
-            key:
-              type: string
-              description: Header name
-            value:
+            id:
               type: string
-              description: Header value
+              description: Unique identifier for the header entry
+            cells:
+              type: object
+              required:
+                - Key
+                - Value
+              properties:
+                Key:
+                  type: string
+                  description: Header name
+                Value:
+                  type: string
+                  description: Header value
       body:
         type: string
         description: Request body for POST/PUT/PATCH methods
@@ -99,15 +123,21 @@ user-api:
     url: "https://api.example.com/users/123"
     method: GET
     headers:
-      - key: "Authorization"
-        value: "Bearer {{API_TOKEN}}"
-      - key: "Content-Type"
-        value: "application/json"
+      - id: header-1-uuid-here
+        cells:
+          Key: "Authorization"
+          Value: "Bearer {{API_TOKEN}}"
+      - id: header-2-uuid-here
+        cells:
+          Key: "Content-Type"
+          Value: "application/json"
   connections:
     success: process-user-data
     error: handle-api-error
 ```
 
+
+
 ### POST Request with Body
 
 ```yaml
@@ -118,10 +148,14 @@ create-ticket:
     url: "https://api.support.com/tickets"
     method: POST
     headers:
-      - key: "Authorization"
-        value: "Bearer {{SUPPORT_API_KEY}}"
-      - key: "Content-Type"
-        value: "application/json"
+      - id: auth-header-uuid
+        cells:
+          Key: "Authorization"
+          Value: "Bearer {{SUPPORT_API_KEY}}"
+      - id: content-type-uuid
+        cells:
+          Key: "Content-Type"
+          Value: "application/json"
     body: |
       {
         "title": "<agent.title>",
@@ -142,32 +176,249 @@ search-api:
   inputs:
     url: "https://api.store.com/products"
     method: GET
-    queryParams:
-      - key: "q"
-        value: <start.searchTerm>
-      - key: "limit"
-        value: "10"
-      - key: "category"
-        value: <filter.category>
+    params:
+      - id: search-param-uuid
+        cells:
+          Key: "q"
+          Value: <start.searchTerm>
+      - id: limit-param-uuid
+        cells:
+          Key: "limit"
+          Value: "10"
+      - id: category-param-uuid
+        cells:
+          Key: "category"
+          Value: <filter.category>
     headers:
-      - key: "Authorization"
-        value: "Bearer {{STORE_API_KEY}}"
+      - id: auth-header-uuid
+        cells:
+          Key: "Authorization"
+          Value: "Bearer {{STORE_API_KEY}}"
   connections:
     success: display-results
 ```
 
+## Parameter Format
+
+Headers and params (query parameters) use the table format with the following structure:
+
+```yaml
+headers:
+  - id: unique-identifier-here
+    cells:
+      Key: "Content-Type"
+      Value: "application/json"
+  - id: another-unique-identifier
+    cells:
+      Key: "Authorization"
+      Value: "Bearer {{API_TOKEN}}"
+
+params:
+  - id: param-identifier-here
+    cells:
+      Key: "limit"
+      Value: "10"
+```
+
+**Structure Details:**
+- `id`: Unique identifier for tracking the table row
+- `cells.Key`: The parameter/header name
+- `cells.Value`: The parameter/header value
+- This format allows for proper table management and UI state preservation
+
 ## Output References
 
-After an API block executes, you can reference its outputs:
+After an API block executes, you can reference its outputs in subsequent blocks. The API block provides three main outputs:
+
+### Available Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `data` | any | The response body/payload from the API |
+| `status` | number | HTTP status code (200, 404, 500, etc.) |
+| `headers` | object | Response headers returned by the server |
+
+### Usage Examples
+
+```yaml
+# Reference API response data
+process-data:
+  type: function
+  name: "Process API Data"
+  inputs:
+    code: |
+      const responseData = <fetchuserdata.data>;
+      const statusCode = <fetchuserdata.status>;
+      const responseHeaders = <fetchuserdata.headers>;
+      
+      if (statusCode === 200) {
+        return {
+          success: true,
+          user: responseData,
+          contentType: responseHeaders['content-type']
+        };
+      } else {
+        return {
+          success: false,
+          error: `API call failed with status ${statusCode}`
+        };
+      }
+
+# Use API data in an agent block
+analyze-response:
+  type: agent
+  name: "Analyze Response"
+  inputs:
+    userPrompt: |
+      Analyze this API response:
+      
+      Status: <fetchuserdata.status>
+      Data: <fetchuserdata.data>
+      
+      Provide insights about the response.
+
+# Conditional logic based on status
+check-status:
+  type: condition
+  name: "Check API Status"
+  inputs:
+    condition: <fetchuserdata.status> === 200
+  connections:
+    true: success-handler
+    false: error-handler
+```
+
+### Practical Example
 
 ```yaml
-# In subsequent blocks
-next-block:
+user-api:
+  type: api
+  name: "Fetch User Data"
   inputs:
-    data: <api-block-name.output>        # Response data
-    status: <api-block-name.status>      # HTTP status code  
-    headers: <api-block-name.headers>    # Response headers
-    error: <api-block-name.error>        # Error details (if any)
+    url: "https://api.example.com/users/123"
+    method: GET
+  connections:
+    success: process-response
+
+process-response:
+  type: function
+  name: "Process Response"
+  inputs:
+    code: |
+      const user = <fetchuserdata.data>;
+      const status = <fetchuserdata.status>;
+      
+      console.log(`API returned status: ${status}`);
+      console.log(`User data:`, user);
+      
+      return {
+        userId: user.id,
+        email: user.email,
+        isActive: status === 200
+      };
+```
+
+### Error Handling
+
+```yaml
+api-with-error-handling:
+  type: api
+  name: "API Call"
+  inputs:
+    url: "https://api.example.com/data"
+    method: GET
+  connections:
+    success: check-response
+    error: handle-error
+
+check-response:
+  type: condition
+  name: "Check Response Status"
+  inputs:
+    condition: <apicall.status> >= 200 && <apicall.status> < 300
+  connections:
+    true: process-success
+    false: handle-api-error
+
+process-success:
+  type: function
+  name: "Process Success"
+  inputs:
+    code: |
+      return {
+        success: true,
+        data: <apicall.data>,
+        message: "API call successful"
+      };
+
+handle-api-error:
+  type: function
+  name: "Handle API Error"
+  inputs:
+    code: |
+      return {
+        success: false,
+        status: <apicall.status>,
+        error: "API call failed",
+        data: <apicall.data>
+      };
+```
+
+## YAML String Escaping
+
+When writing YAML, certain strings must be quoted to be properly parsed:
+
+### Strings That Must Be Quoted
+
+```yaml
+# URLs with hyphens, colons, special characters
+url: "https://api.example.com/users/123"
+url: "https://my-api.example.com/data"
+
+# Header values with hyphens or special characters  
+headers:
+  - id: header-uuid
+    cells:
+      Key: "User-Agent"
+      Value: "My-Application/1.0"
+  - id: auth-uuid
+    cells:
+      Key: "Authorization" 
+      Value: "Bearer my-token-123"
+
+# Parameter values with hyphens
+params:
+  - id: param-uuid
+    cells:
+      Key: "sort-by"
+      Value: "created-at"
+```
+
+### When to Use Quotes
+
+- ✅ **Always quote**: URLs, tokens, values with hyphens, colons, or special characters
+- ✅ **Always quote**: Values that start with numbers but should be strings
+- ✅ **Always quote**: Boolean-looking strings that should remain as strings
+- ❌ **Don't quote**: Simple alphanumeric strings without special characters
+
+### Examples
+
+```yaml
+# ✅ Correct
+url: "https://api.stripe.com/v1/charges"
+headers:
+  - id: auth-header
+    cells:
+      Key: "Authorization"
+      Value: "Bearer sk-test-123456789"
+
+# ❌ Incorrect (may cause parsing errors)
+url: https://api.stripe.com/v1/charges
+headers:
+  - id: auth-header
+    cells:
+      Key: Authorization
+      Value: Bearer sk-test-123456789
 ```
 
 ## Best Practices
@@ -176,4 +427,5 @@ next-block:
 - Include error handling with error connections
 - Set appropriate timeouts for your use case
 - Validate response status codes in subsequent blocks
-- Use meaningful block names for easier reference 
+- Use meaningful block names for easier reference
+- **Always quote strings with special characters, URLs, and tokens**