@agent-os-sdk/client 0.1.1 → 0.2.1

package/src/generated/swagger.json

@@ -67,25 +67,9 @@
           "AgentPortability"
         ],
         "summary": "Import an agent bundle.",
-        "parameters": [
-          {
-            "name": "X-Tenant-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "X-Workspace-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          }
-        ],
+        "description": "Imports an agent bundle into the current tenant/workspace.\nThe agent and all versions are created with new IDs to avoid conflicts.\n\n**Security:**\n- Tenant and workspace are resolved from the authenticated context\n- Original IDs from the bundle are replaced with new GUIDs",
         "requestBody": {
+          "description": "The agent bundle to import.",
           "content": {
             "application/json": {
               "schema": {
@@ -105,8 +89,28 @@
           }
         },
         "responses": {
-          "200": {
-            "description": "OK"
+          "201": {
+            "description": "Agent imported successfully."
+          },
+          "400": {
+            "description": "Invalid bundle format.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required or missing workspace context.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -116,7 +120,10 @@
         "tags": [
           "Agents"
         ],
+        "summary": "Creates a new agent in the current workspace.",
+        "description": "Creates a new agent with the specified configuration. The agent is created in draft mode\nand must have a version published before it can be used for runs.\n\n**Example Request:**\n```json\n{\n  \"name\": \"customer-support-agent\",\n  \"description\": \"Handles customer inquiries and support tickets\",\n  \"graph_spec\": { \"nodes\": [...], \"edges\": [...] }\n}\n```",
         "requestBody": {
+          "description": "The agent creation request containing name, description, and optional graph specification.",
           "content": {
             "application/json": {
               "schema": {
@@ -136,8 +143,38 @@
           }
         },
         "responses": {
-          "200": {
-            "description": "OK"
+          "201": {
+            "description": "Agent created successfully. Returns the new agent details."
+          },
+          "400": {
+            "description": "Invalid request body. Check required fields and data formats.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required. Provide a valid Bearer token.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "An agent with this name already exists in the workspace.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -145,10 +182,13 @@
         "tags": [
           "Agents"
         ],
+        "summary": "Lists all agents in the current workspace with pagination.",
+        "description": "Returns a paginated list of agents accessible to the current user within the specified workspace.\nResults are ordered by creation date (newest first).\n\n**Pagination:**\nUse `skip` and `take` parameters to paginate through large result sets.\nDefault page size is 20, maximum is 100.",
         "parameters": [
           {
             "name": "skip",
             "in": "query",
+            "description": "Number of records to skip for pagination. Default: 0.",
             "schema": {
               "type": "integer",
               "format": "int32",
@@ -158,6 +198,7 @@
           {
             "name": "take",
             "in": "query",
+            "description": "Maximum number of records to return. Default: 20, Max: 100.",
             "schema": {
               "type": "integer",
               "format": "int32",
@@ -167,7 +208,27 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the list of agents."
+          },
+          "400": {
+            "description": "X-Workspace-Id header is required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -177,11 +238,13 @@
         "tags": [
           "Agents"
         ],
-        "summary": "Get agent by ID with tenant isolation (IDOR protected)",
+        "summary": "Retrieves a specific agent by its unique identifier.",
+        "description": "Returns the full agent details including configuration, live version reference,\nand metadata. Access is restricted to agents within your tenant (IDOR protected).",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier (GUID) of the agent to retrieve.",
             "required": true,
             "schema": {
               "type": "string",
@@ -191,7 +254,27 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the agent details."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found or not accessible.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -199,11 +282,13 @@
         "tags": [
           "Agents"
         ],
-        "summary": "Update agent by ID with tenant isolation (IDOR protected)",
+        "summary": "Updates an existing agent's metadata and configuration.",
+        "description": "Performs a partial update (PATCH) on the agent. Only provided fields are updated.\n\n**Note:** This updates the agent metadata, not the version. To update the agent's\nbehavior/graph, create a new version instead.\n\n**Example Request:**\n```json\n{\n  \"name\": \"updated-agent-name\",\n  \"description\": \"New description for the agent\"\n}\n```",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier (GUID) of the agent to update.",
             "required": true,
             "schema": {
               "type": "string",
@@ -212,6 +297,7 @@
           }
         ],
         "requestBody": {
+          "description": "The fields to update. Only non-null fields will be modified.",
           "content": {
             "application/json": {
               "schema": {
@@ -232,7 +318,37 @@
         },
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Agent updated successfully. Returns updated agent."
+          },
+          "400": {
+            "description": "Invalid request body.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found or not accessible.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -240,11 +356,13 @@
         "tags": [
           "Agents"
         ],
-        "summary": "Delete agent by ID with tenant isolation (IDOR protected)",
+        "summary": "Deletes an agent from the workspace.",
+        "description": "By default, performs a soft delete (marks as deleted but retains data).\nUse `hardDelete=true` to permanently remove the agent and all associated data.\n\n**Warning:** Hard delete is irreversible and will remove:\n- All agent versions\n- All associated runs and threads\n- All credential bindings",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier (GUID) of the agent to delete.",
             "required": true,
             "schema": {
               "type": "string",
@@ -254,6 +372,7 @@
           {
             "name": "hardDelete",
             "in": "query",
+            "description": "If true, permanently deletes the agent. Default: false (soft delete).",
             "schema": {
               "type": "boolean",
               "default": false
@@ -261,8 +380,28 @@
           }
         ],
         "responses": {
-          "200": {
-            "description": "OK"
+          "204": {
+            "description": "Agent deleted successfully."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found or not accessible.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -272,11 +411,13 @@
         "tags": [
           "Agents"
         ],
-        "summary": "Get Mermaid graph for the live version of an agent.",
+        "summary": "Gets a Mermaid diagram representation of the agent's graph.",
+        "description": "Returns the agent's workflow as a Mermaid diagram string that can be rendered\nin any Mermaid-compatible viewer. Uses the currently live version of the agent.\n\n**Example Response:**\n```json\n{\n  \"mermaid\": \"graph TD\\n    START --> LLM --> END\",\n  \"agent_id\": \"...\",\n  \"live_version_id\": \"...\"\n}\n```",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier (GUID) of the agent.",
             "required": true,
             "schema": {
               "type": "string",
@@ -286,7 +427,27 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the Mermaid graph representation."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found or not accessible.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -362,11 +523,13 @@
         "tags": [
           "AgentVersions"
         ],
-        "summary": "Create agent version with tenant isolation (IDOR protected)",
+        "summary": "Creates a new version for an agent.",
+        "description": "Creates an immutable snapshot of the agent's configuration. The new version\ncan optionally be marked as the live version immediately.\n\n**Example Request:**\n```json\n{\n  \"version_tag\": \"v1.2.0\",\n  \"graph_spec\": { \"nodes\": [...], \"edges\": [...] },\n  \"set_live\": true\n}\n```",
         "parameters": [
           {
             "name": "agentId",
             "in": "path",
+            "description": "The unique identifier of the parent agent.",
             "required": true,
             "schema": {
               "type": "string",
@@ -375,6 +538,7 @@
           }
         ],
         "requestBody": {
+          "description": "The version creation request with graph specification.",
           "content": {
             "application/json": {
               "schema": {
@@ -392,27 +556,334 @@
               }
             }
           }
-        },
-        "responses": {
-          "200": {
-            "description": "OK"
-          }
+        },
+        "responses": {
+          "201": {
+            "description": "Version created successfully."
+          },
+          "400": {
+            "description": "Invalid request body or validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Parent agent not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "AgentVersions"
+        ],
+        "summary": "Lists all versions for an agent.",
+        "description": "Returns all versions of the specified agent, ordered by creation date (newest first).\nThe response includes which version is currently set as \"live\".",
+        "parameters": [
+          {
+            "name": "agentId",
+            "in": "path",
+            "description": "The unique identifier of the agent.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Returns the list of versions."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/api/agents/{agentId}/versions/{versionId}": {
+      "get": {
+        "tags": [
+          "AgentVersions"
+        ],
+        "summary": "Retrieves a specific version by its identifier.",
+        "description": "Returns the full details of a specific agent version, including its\ngraph specification and all configuration settings.",
+        "parameters": [
+          {
+            "name": "agentId",
+            "in": "path",
+            "description": "The unique identifier of the parent agent.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "versionId",
+            "in": "path",
+            "description": "The unique identifier of the version to retrieve.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Returns the version details."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Version not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "AgentVersions"
+        ],
+        "summary": "Updates are not allowed - versions are immutable.",
+        "description": "Agent versions are immutable by design. This endpoint always returns a 409 Conflict\nto enforce this invariant. To change an agent's behavior, create a new version instead.\n\n**Why immutability?**\n- Reproducibility: Every run can be traced to an exact version\n- Auditability: Version history provides a complete changelog\n- Rollback: Easy to revert to any previous version",
+        "parameters": [
+          {
+            "name": "agentId",
+            "in": "path",
+            "description": "The unique identifier of the parent agent.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "versionId",
+            "in": "path",
+            "description": "The unique identifier of the version.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "The update request (ignored - updates not allowed).",
+          "content": {
+            "application/json": {
+              "schema": { }
+            },
+            "text/json": {
+              "schema": { }
+            },
+            "application/*+json": {
+              "schema": { }
+            }
+          }
+        },
+        "responses": {
+          "409": {
+            "description": "Versions are immutable. Create a new version instead.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/api/tokens": {
+      "get": {
+        "tags": [
+          "ApiTokens"
+        ],
+        "summary": "Lists all API tokens for the current workspace.",
+        "description": "Returns token metadata without secrets. Token secrets are only\navailable at creation time and cannot be retrieved later.",
+        "responses": {
+          "200": {
+            "description": "Returns the list of tokens."
+          },
+          "400": {
+            "description": "Workspace ID header is required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "ApiTokens"
+        ],
+        "summary": "Create a new API token.\nThe token secret is only returned once on creation.",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateTokenRequest"
+              }
+            },
+            "text/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateTokenRequest"
+              }
+            },
+            "application/*+json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateTokenRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/v1/api/tokens/{id}": {
+      "delete": {
+        "tags": [
+          "ApiTokens"
+        ],
+        "summary": "Revoke an API token immediately.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/v1/api/tokens/{id}/rotate": {
+      "post": {
+        "tags": [
+          "ApiTokens"
+        ],
+        "summary": "Rotate an API token - revokes current and issues a new one.\nThe new token secret is only returned once.",
+        "description": "Rotation is useful for security hygiene (periodic credential rotation)\nor when a token may have been compromised. The new token inherits\nthe same scopes and expiration policy as the original.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Token ID to rotate.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Token rotated successfully, new secret returned."
+          },
+          "404": {
+            "description": "Token not found or already revoked.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
         }
-      },
+      }
+    },
+    "/v1/api/workspaces/{workspaceId}/approvals": {
       "get": {
         "tags": [
-          "AgentVersions"
+          "Approvals"
         ],
-        "summary": "List agent versions with tenant isolation (IDOR protected)",
+        "summary": "List approvals for a workspace, optionally filtered by status.",
         "parameters": [
           {
-            "name": "agentId",
+            "name": "workspaceId",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string",
               "format": "uuid"
             }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 50
+            }
           }
         ],
         "responses": {
@@ -422,15 +893,15 @@
         }
       }
     },
-    "/v1/api/agents/{agentId}/versions/{versionId}": {
+    "/v1/api/workspaces/{workspaceId}/approvals/{approvalId}": {
       "get": {
         "tags": [
-          "AgentVersions"
+          "Approvals"
         ],
-        "summary": "Get specific version with tenant isolation (IDOR protected)",
+        "summary": "Get a specific approval by ID.",
         "parameters": [
           {
-            "name": "agentId",
+            "name": "workspaceId",
             "in": "path",
             "required": true,
             "schema": {
@@ -439,7 +910,7 @@
             }
           },
           {
-            "name": "versionId",
+            "name": "approvalId",
             "in": "path",
             "required": true,
             "schema": {
@@ -453,15 +924,17 @@
             "description": "OK"
           }
         }
-      },
-      "patch": {
+      }
+    },
+    "/v1/api/workspaces/{workspaceId}/approvals/{approvalId}/decision": {
+      "post": {
         "tags": [
-          "AgentVersions"
+          "Approvals"
         ],
-        "summary": "Agent versions are immutable once published. Updates are not allowed.",
+        "summary": "Decide on an approval: approve or deny.\nIdempotent: re-deciding returns 200 no-op.",
         "parameters": [
           {
-            "name": "agentId",
+            "name": "workspaceId",
             "in": "path",
             "required": true,
             "schema": {
@@ -470,7 +943,7 @@
             }
           },
           {
-            "name": "versionId",
+            "name": "approvalId",
             "in": "path",
             "required": true,
             "schema": {
@@ -479,58 +952,21 @@
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": { }
-            },
-            "text/json": {
-              "schema": { }
-            },
-            "application/*+json": {
-              "schema": { }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "OK"
-          }
-        }
-      }
-    },
-    "/v1/api/tokens": {
-      "get": {
-        "tags": [
-          "ApiTokens"
-        ],
-        "summary": "List all API tokens for the current workspace.\nToken secrets are never returned.",
-        "responses": {
-          "200": {
-            "description": "OK"
-          }
-        }
-      },
-      "post": {
-        "tags": [
-          "ApiTokens"
-        ],
-        "summary": "Create a new API token.\nThe token secret is only returned once on creation.",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateTokenRequest"
+                "$ref": "#/components/schemas/ApprovalDecision"
               }
             },
             "text/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateTokenRequest"
+                "$ref": "#/components/schemas/ApprovalDecision"
               }
             },
             "application/*+json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateTokenRequest"
+                "$ref": "#/components/schemas/ApprovalDecision"
               }
             }
           }
@@ -542,30 +978,6 @@
         }
       }
     },
-    "/v1/api/tokens/{id}": {
-      "delete": {
-        "tags": [
-          "ApiTokens"
-        ],
-        "summary": "Revoke an API token immediately.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "OK"
-          }
-        }
-      }
-    },
     "/v1/api/audit": {
       "get": {
         "tags": [
@@ -724,6 +1136,92 @@
         }
       }
     },
+    "/v1/api/builder/{agentId}/chat": {
+      "post": {
+        "tags": [
+          "Builder"
+        ],
+        "summary": "Chat with the Meta-Agent to modify an agent's graph.\nReturns SSE stream: message, graph_update, done events.",
+        "parameters": [
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            },
+            "text/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            },
+            "application/*+json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/v1/api/builder/{agentId}/chat/sync": {
+      "post": {
+        "tags": [
+          "Builder"
+        ],
+        "summary": "Synchronous version of builder chat (for testing).",
+        "parameters": [
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            },
+            "text/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            },
+            "application/*+json": {
+              "schema": {
+                "$ref": "#/components/schemas/BuilderChatRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
     "/v1/api/workspaces/{workspaceId}/runs/{runId}/checkpoints": {
       "get": {
         "tags": [
@@ -754,40 +1252,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointListResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CheckpointListResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointListResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -841,20 +1319,10 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointDetail"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CheckpointDetail"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointDetail"
-                }
               }
             }
           }
@@ -900,40 +1368,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointDetail"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CheckpointDetail"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointDetail"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -998,40 +1446,20 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReplayResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ReplayResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReplayResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -1043,18 +1471,13 @@
         "tags": [
           "Credentials"
         ],
+        "summary": "Lists all credentials accessible to the current tenant/workspace.",
+        "description": "Returns credentials the user has access to. Does not expose the encrypted values,\nonly metadata like name, type, scope, and status.",
         "parameters": [
-          {
-            "name": "X-Tenant-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "workspaceId",
             "in": "query",
+            "description": "Optional filter by workspace.",
             "schema": {
               "type": "string",
               "format": "uuid"
@@ -1063,7 +1486,17 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the list of credentials."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -1071,17 +1504,10 @@
         "tags": [
           "Credentials"
         ],
-        "parameters": [
-          {
-            "name": "X-Member-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          }
-        ],
+        "summary": "Creates a new credential.",
+        "description": "Creates a new encrypted credential for storing API keys or secrets.\nThe credential is encrypted at rest using workspace-specific keys.",
         "requestBody": {
+          "description": "The credential configuration.",
           "content": {
             "application/json": {
               "schema": {
@@ -1098,11 +1524,31 @@
                 "$ref": "#/components/schemas/CreateCredentialRequest"
               }
             }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "OK"
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Credential created successfully."
+          },
+          "400": {
+            "description": "Invalid request (missing TypeId or WorkspaceId).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -1112,26 +1558,21 @@
         "tags": [
           "Credentials"
         ],
+        "summary": "Updates an existing credential.",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The credential ID.",
             "required": true,
             "schema": {
               "type": "string",
               "format": "uuid"
             }
-          },
-          {
-            "name": "X-Member-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
           }
         ],
         "requestBody": {
+          "description": "The update payload.",
           "content": {
             "application/json": {
               "schema": {
@@ -1152,7 +1593,17 @@
         },
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Credential updated successfully."
+          },
+          "404": {
+            "description": "Credential not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -1162,26 +1613,21 @@
         "tags": [
           "Credentials"
         ],
+        "summary": "Grants access to a credential for a workspace.",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The credential ID.",
             "required": true,
             "schema": {
               "type": "string",
               "format": "uuid"
             }
-          },
-          {
-            "name": "X-Member-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
           }
         ],
         "requestBody": {
+          "description": "The grant configuration.",
           "content": {
             "application/json": {
               "schema": {
@@ -1202,7 +1648,17 @@
         },
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Access granted successfully."
+          },
+          "404": {
+            "description": "Credential not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -1212,28 +1668,32 @@
         "tags": [
           "Credentials"
         ],
+        "summary": "Revokes access to a credential.",
         "parameters": [
           {
             "name": "accessId",
             "in": "path",
+            "description": "The access grant ID to revoke.",
             "required": true,
             "schema": {
               "type": "string",
               "format": "uuid"
             }
-          },
-          {
-            "name": "X-Member-Id",
-            "in": "header",
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
           }
         ],
         "responses": {
-          "200": {
-            "description": "OK"
+          "204": {
+            "description": "Access revoked successfully."
+          },
+          "404": {
+            "description": "Access grant not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -1921,40 +2381,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/PresignedUploadResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PresignedUploadResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PresignedUploadResponse"
-                }
               }
             }
           },
           "400": {
             "description": "Bad Request",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -2010,60 +2450,30 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileConfirmResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/FileConfirmResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileConfirmResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           },
           "400": {
             "description": "Bad Request",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -2100,40 +2510,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/PresignedDownloadResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PresignedDownloadResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PresignedDownloadResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -2186,14 +2576,6 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/FileListItem"
-                  }
-                }
-              },
               "application/json": {
                 "schema": {
                   "type": "array",
@@ -2201,14 +2583,6 @@
                     "$ref": "#/components/schemas/FileListItem"
                   }
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/FileListItem"
-                  }
-                }
               }
             }
           }
@@ -2245,40 +2619,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileDetail"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/FileDetail"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileDetail"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -2316,20 +2670,10 @@
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3287,7 +3631,8 @@
         "tags": [
           "Runs"
         ],
-        "summary": "Lists runs with optional filtering.",
+        "summary": "Lists runs with optional filtering and pagination.",
+        "description": "Returns a paginated list of runs with filtering options. Results are ordered\nby creation date (newest first).\n\n**Filtering:**\n- `agentId`: Show only runs for a specific agent\n- `threadId`: Show only runs in a specific thread\n- `status`: Filter by status (queued, running, completed, failed, canceled)",
         "parameters": [
           {
             "name": "agentId",
@@ -3310,7 +3655,7 @@
           {
             "name": "status",
             "in": "query",
-            "description": "Optional filter by status.",
+            "description": "Optional filter by status (queued, running, completed, failed, canceled).",
             "schema": {
               "type": "string"
             }
@@ -3318,7 +3663,7 @@
           {
             "name": "limit",
             "in": "query",
-            "description": "Max results to return (default 20, max 100).",
+            "description": "Max results to return. Default: 20, Max: 100.",
             "schema": {
               "type": "integer",
               "format": "int32",
@@ -3328,7 +3673,7 @@
           {
             "name": "offset",
             "in": "query",
-            "description": "Pagination offset.",
+            "description": "Number of records to skip for pagination.",
             "schema": {
               "type": "integer",
               "format": "int32",
@@ -3338,21 +3683,21 @@
         ],
         "responses": {
           "200": {
-            "description": "OK",
+            "description": "Returns the list of runs.",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunListResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RunListResponse"
                 }
-              },
-              "text/json": {
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/RunListResponse"
+                  "$ref": "#/components/schemas/ProblemDetails"
                 }
               }
             }
@@ -3363,10 +3708,10 @@
         "tags": [
           "Runs"
         ],
-        "summary": "Starts a new agent run.",
-        "description": "Resolves or creates a thread and identifies the correct agent version before queuing the run.\nSupports Idempotency-Key header for idempotent request handling.",
+        "summary": "Starts a new agent run asynchronously.",
+        "description": "Creates a new run and queues it for execution. The run will be processed\nby the data plane and its status can be monitored via polling or SSE.\n\n**Thread Resolution:**\n- If `thread.id` is provided, uses existing thread\n- If `thread` is omitted, creates a new thread automatically\n\n**Idempotency:**\nProvide `Idempotency-Key` header to prevent duplicate runs.\nIf a run with the same key exists and is still valid, returns 200 instead of 201.\n\n**Example Request:**\n```json\n{\n  \"agent_id\": \"...\",\n  \"input\": { \"messages\": [{ \"role\": \"user\", \"content\": \"Hello\" }] }\n}\n```",
         "requestBody": {
-          "description": "The run request details.",
+          "description": "The run request with agent ID and input.",
           "content": {
             "application/json": {
               "schema": {
@@ -3387,19 +3732,19 @@
         },
         "responses": {
           "201": {
-            "description": "Created",
+            "description": "Run created and queued successfully.",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RunResponse"
                 }
-              },
-              "text/json": {
+              }
+            }
+          },
+          "200": {
+            "description": "Existing run returned (idempotent request).",
+            "content": {
+              "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RunResponse"
                 }
@@ -3407,19 +3752,19 @@
             }
           },
           "400": {
-            "description": "Bad Request",
+            "description": "Invalid request (missing agent, invalid input).",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
@@ -3451,40 +3796,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunDetailResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RunDetailResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunDetailResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3533,37 +3858,80 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunEventsResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RunEventsResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunEventsResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
+              "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/api/runs/{runId}/events/stream": {
+      "get": {
+        "tags": [
+          "Runs"
+        ],
+        "summary": "Wave 1.0: Get run events for polling-based replay.\nReturns events after a specific sequence number for incremental polling.",
+        "description": "This is the recommended endpoint for SDK/UI event consumption.\nEvents are ordered by sequence number (ascending) and limited to prevent\nlarge responses. Use `next_after_seq` for pagination.\n\n**Security:** Only returns events for runs in the caller's workspace.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "description": "The unique ID of the run.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "afterSeq",
+            "in": "query",
+            "description": "Return events with seq greater than this value (default: 0 = all).",
+            "schema": {
+              "type": "integer",
+              "format": "int64",
+              "default": 0
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Max events to return (default: 100, max: 500).",
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
+                  "$ref": "#/components/schemas/RunEventsPollResponse"
                 }
-              },
-              "text/json": {
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
@@ -3603,60 +3971,30 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/WaitRunResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WaitRunResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/WaitRunResponse"
-                }
               }
             }
           },
           "408": {
             "description": "Request Timeout",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           },
           "400": {
             "description": "Bad Request",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3693,40 +4031,20 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/BatchRunResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/BatchRunResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/BatchRunResponse"
-                }
               }
             }
           },
           "400": {
             "description": "Bad Request",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3763,9 +4081,10 @@
         "tags": [
           "Runs"
         ],
-        "summary": "Starts a run and streams updates via SSE.",
+        "summary": "Creates a run and streams real-time updates via Server-Sent Events (SSE).",
+        "description": "This is the recommended endpoint for interactive applications. It creates\na run and maintains an open SSE connection to stream events in real-time.\n\n**SSE Events:**\n- `start`: Run created and queued\n- `update`: Run status changed\n- `complete`: Run finished successfully (includes output)\n- `error`: Run failed or was canceled (includes error details)\n\n**Example Event Stream:**\n```\nevent: start\ndata: {\"run_id\": \"...\", \"status\": \"queued\"}\n\nevent: update\ndata: {\"run_id\": \"...\", \"status\": \"running\"}\n\nevent: complete\ndata: {\"run_id\": \"...\", \"status\": \"completed\", \"output\": {...}}\n```",
         "requestBody": {
-          "description": "The stream run request.",
+          "description": "The run request with agent ID and input.",
           "content": {
             "application/json": {
               "schema": {
@@ -3833,40 +4152,20 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/RerunResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RerunResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/RerunResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3922,40 +4221,20 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReplayResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ReplayResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReplayResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -3983,40 +4262,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointIndexResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CheckpointIndexResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CheckpointIndexResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -4063,60 +4322,30 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ResumeResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ResumeResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ResumeResponse"
-                }
               }
             }
           },
           "400": {
             "description": "Bad Request",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -4163,40 +4392,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/CancelRunResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CancelRunResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CancelRunResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -4529,8 +4738,10 @@
         "tags": [
           "Threads"
         ],
-        "summary": "Create a new thread.",
+        "summary": "Creates a new conversation thread.",
+        "description": "Creates an empty thread that can be used for agent runs. Threads persist\nconversation state between multiple runs.\n\n**Example Request:**\n```json\n{\n  \"channel\": \"http\",\n  \"metadata\": { \"user_id\": \"abc123\" }\n}\n```",
         "requestBody": {
+          "description": "Thread creation options including channel and metadata.",
           "content": {
             "application/json": {
               "schema": {
@@ -4550,8 +4761,18 @@
           }
         },
         "responses": {
-          "200": {
-            "description": "OK"
+          "201": {
+            "description": "Thread created successfully."
+          },
+          "401": {
+            "description": "Authentication required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -4582,11 +4803,13 @@
         "tags": [
           "Threads"
         ],
-        "summary": "Get a thread by ID.",
+        "summary": "Retrieves a thread by its unique identifier.",
+        "description": "Returns the thread details including channel, external ID, and metadata.\nAccess is restricted to threads within your tenant (IDOR protected).",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier of the thread.",
             "required": true,
             "schema": {
               "type": "string",
@@ -4596,7 +4819,17 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the thread."
+          },
+          "404": {
+            "description": "Thread not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -4628,11 +4861,13 @@
         "tags": [
           "Threads"
         ],
-        "summary": "Get comprehensive thread state summary.\nReturns last checkpoint, run status, message count, and pointers for UI.",
+        "summary": "Gets a comprehensive state summary for a thread.",
+        "description": "Returns aggregated information about the thread including:\n- Run count and status of the last run\n- Last checkpoint information\n- Message count\n- Pointers to related endpoints (runs, messages, history)\n\nThis is the recommended endpoint for building thread detail UIs.",
         "parameters": [
           {
             "name": "id",
             "in": "path",
+            "description": "The unique identifier of the thread.",
             "required": true,
             "schema": {
               "type": "string",
@@ -4642,7 +4877,17 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "Returns the thread state summary."
+          },
+          "404": {
+            "description": "Thread not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -5586,11 +5831,13 @@
         "tags": [
           "VectorStores"
         ],
-        "summary": "Create a new vector store.",
+        "summary": "Creates a new vector store for semantic document search.",
+        "description": "Creates a vector store with the specified embedding configuration.\nThe store is ready to accept file attachments immediately after creation.\n\n**Default Configuration:**\n- Provider: `openai`\n- Model: `text-embedding-3-small`\n- Dimension: `1536`",
         "parameters": [
           {
             "name": "workspaceId",
             "in": "path",
+            "description": "The workspace to create the vector store in.",
             "required": true,
             "schema": {
               "type": "string",
@@ -5599,6 +5846,7 @@
           }
         ],
         "requestBody": {
+          "description": "Vector store configuration.",
           "content": {
             "application/json": {
               "schema": {
@@ -5619,21 +5867,21 @@
         },
         "responses": {
           "201": {
-            "description": "Created",
+            "description": "Vector store created successfully.",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorStoreResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/VectorStoreResponse"
                 }
-              },
-              "text/json": {
+              }
+            }
+          },
+          "404": {
+            "description": "Workspace not found.",
+            "content": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/VectorStoreResponse"
+                  "$ref": "#/components/schemas/ProblemDetails"
                 }
               }
             }
@@ -5678,14 +5926,6 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/VectorStoreResponse"
-                  }
-                }
-              },
               "application/json": {
                 "schema": {
                   "type": "array",
@@ -5693,14 +5933,6 @@
                     "$ref": "#/components/schemas/VectorStoreResponse"
                   }
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/VectorStoreResponse"
-                  }
-                }
               }
             }
           }
@@ -5737,40 +5969,20 @@
           "200": {
             "description": "OK",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorStoreResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/VectorStoreResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorStoreResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -5808,20 +6020,10 @@
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -5877,40 +6079,20 @@
           "201": {
             "description": "Created",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorStoreFileResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/VectorStoreFileResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorStoreFileResponse"
-                }
               }
             }
           },
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -5922,11 +6104,13 @@
         "tags": [
           "VectorStores"
         ],
-        "summary": "Query the vector store using semantic search.",
+        "summary": "Performs semantic similarity search against the vector store.",
+        "description": "Executes a cosine similarity search to find document chunks most relevant\nto the query. Results are ranked by similarity score.\n\n**Note:** The query is automatically embedded using the store's configured\nembedding provider before search.\n\n**Example Request:**\n```json\n{\n  \"query\": \"How do I configure authentication?\",\n  \"top_k\": 5,\n  \"min_score\": 0.7\n}\n```",
         "parameters": [
           {
             "name": "workspaceId",
             "in": "path",
+            "description": "The workspace containing the vector store.",
             "required": true,
             "schema": {
               "type": "string",
@@ -5936,6 +6120,7 @@
           {
             "name": "vectorStoreId",
             "in": "path",
+            "description": "The vector store to query.",
             "required": true,
             "schema": {
               "type": "string",
@@ -5944,6 +6129,7 @@
           }
         ],
         "requestBody": {
+          "description": "Query parameters including text and result limits.",
           "content": {
             "application/json": {
               "schema": {
@@ -5964,42 +6150,22 @@
         },
         "responses": {
           "200": {
-            "description": "OK",
+            "description": "Returns matching results.",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorQueryResponse"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/VectorQueryResponse"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/VectorQueryResponse"
-                }
               }
             }
           },
           "404": {
-            "description": "Not Found",
+            "description": "Vector store not found.",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -6058,20 +6224,10 @@
           "404": {
             "description": "Not Found",
             "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
-              },
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ProblemDetails"
                 }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDetails"
-                }
               }
             }
           }
@@ -6447,6 +6603,20 @@
         },
         "additionalProperties": false
       },
+      "ApprovalDecision": {
+        "type": "object",
+        "properties": {
+          "decision": {
+            "type": "string",
+            "nullable": true
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false
+      },
       "AttachFileRequest": {
         "type": "object",
         "properties": {
@@ -6559,6 +6729,24 @@
         },
         "additionalProperties": false
       },
+      "BuilderChatRequest": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "nullable": true
+          },
+          "current_graph_spec": {
+            "nullable": true
+          },
+          "thread_id": {
+            "type": "string",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "Request DTO for builder chat."
+      },
       "CancelRequest": {
         "type": "object",
         "properties": {
@@ -7722,6 +7910,35 @@
         },
         "additionalProperties": false
       },
+      "RunEventDto": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "seq": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "type": {
+            "type": "string",
+            "nullable": true
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "attempt_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "payload": {
+            "nullable": true
+          }
+        },
+        "additionalProperties": false
+      },
       "RunEventItem": {
         "type": "object",
         "properties": {
@@ -7743,6 +7960,30 @@
         },
         "additionalProperties": false
       },
+      "RunEventsPollResponse": {
+        "type": "object",
+        "properties": {
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunEventDto"
+            },
+            "nullable": true
+          },
+          "latest_seq": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "next_after_seq": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "has_more": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
       "RunEventsResponse": {
         "type": "object",
         "properties": {
@@ -8466,9 +8707,15 @@
     {
       "name": "ApiTokens"
     },
+    {
+      "name": "Approvals"
+    },
     {
       "name": "Audit"
     },
+    {
+      "name": "Builder"
+    },
     {
       "name": "Checkpoints"
     },