{"openapi":"3.1.0","info":{"version":"1.0.0","title":"VoltAgent Core API","description":"API for managing and interacting with VoltAgents"},"servers":[{"url":"http://localhost:3000","description":"Local development server"}],"components":{"schemas":{"PathParam.id":{"type":"string","minLength":1,"description":"The ID of the agent","example":"my-agent-123"},"QueryParam.userId":{"type":"string","minLength":1,"description":"User ID for resumable streams","example":"user-123"},"PathParam.conversationId":{"type":"string","minLength":1,"description":"The ID of the conversation","example":"chat_123"},"PathParam.executionId":{"type":"string","minLength":1,"description":"The ID of the execution to operate on","example":"exec_1234567890_abc123"},"PathParam.name":{"type":"string","minLength":1,"description":"The name of the tool","example":"web_search"}},"parameters":{}},"paths":{"/agents":{"get":{"tags":["Agent Management"],"summary":"List all registered agents","description":"Retrieve a comprehensive list of all agents registered in the system. Each agent includes its configuration, status, model information, tools, sub-agents, and memory settings. Use this endpoint to discover available agents and their capabilities.","responses":{"200":{"description":"Successfully retrieved list of all registered agents","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","description":"Current status of the agent"},"model":{"type":"string"},"tools":{"type":"array","items":{"nullable":true}},"subAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","description":"Current status of the sub-agent"},"model":{"type":"string"},"tools":{"type":"array","items":{"nullable":true}},"memory":{"nullable":true}},"required":["id","name","description","status","model"]},"description":"List of sub-agents"},"memory":{"nullable":true},"isTelemetryEnabled":{"type":"boolean","description":"Indicates if telemetry is configured for the agent"}},"required":["id","name","description","status","model","tools","isTelemetryEnabled"]},"description":"Array of agent objects with their configurations"}},"required":["success","data"]}}}},"500":{"description":"Failed to retrieve agents due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/text":{"post":{"tags":["Agent Generation"],"summary":"Generate text response","description":"Generate a text response from an agent using the provided conversation history. This endpoint processes messages synchronously and returns the complete response once generation is finished. Use this for traditional request-response interactions where you need the full response before proceeding.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"anyOf":[{"type":"string","description":"Direct text input"},{"type":"array","items":{"nullable":true},"description":"AI SDK message array (UIMessage or ModelMessage format)"}],"description":"Input text or messages array - accepts string, UIMessage[], or ModelMessage[]"},"options":{"type":"object","properties":{"memory":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation identifier for memory scoping"},"userId":{"type":"string","description":"User identifier for memory scoping"},"options":{"type":"object","properties":{"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of previous messages to include from memory"},"readOnly":{"type":"boolean","description":"When true, memory reads are allowed but no memory writes are persisted"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Semantic retrieval configuration for this call"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Per-call conversation persistence behavior"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Per-call persisted assistant message metadata behavior"}},"description":"Per-call memory behavior overrides"}},"description":"Runtime memory envelope (preferred): memory.userId/memory.conversationId + memory.options.*"},"userId":{"type":"string","description":"Deprecated: use options.memory.userId"},"conversationId":{"type":"string","description":"Deprecated: use options.memory.conversationId"},"context":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Deprecated: use options.memory.options.contextLimit"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Deprecated: use options.memory.options.semanticMemory"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Deprecated: use options.memory.options.conversationPersistence"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Deprecated: use options.memory.options.messageMetadataPersistence"},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Maximum number of steps for this request"},"temperature":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Controls randomness (0-1)"},"maxOutputTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":4000,"description":"Maximum tokens to generate"},"topP":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Controls diversity via nucleus sampling (0-1)"},"frequencyPenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes repeated tokens (0-2)"},"presencePenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes tokens based on presence (0-2)"},"seed":{"type":"integer","description":"Optional seed for reproducible results"},"stopSequences":{"type":"array","items":{"type":"string"},"description":"Stop sequences to end generation"},"providerOptions":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"},"resumableStream":{"type":"boolean","description":"When true, avoids wiring the HTTP abort signal into streams so they can be resumed (requires resumable streams and conversation/user IDs via options.memory or top-level legacy fields). If omitted, server defaults may apply."},"output":{"type":"object","properties":{"type":{"type":"string","enum":["object","text"],"description":"Output type: 'object' for structured JSON, 'text' for text-only output"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"JSON schema for structured output (required when type is 'object')"}},"required":["type"],"description":"Structured output configuration for schema-guided generation"},"feedback":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Feedback key for the trace"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"expiresAt":{"type":"string","description":"Absolute expiration timestamp (ISO 8601)"},"expiresIn":{"type":"object","properties":{"days":{"type":"integer"},"hours":{"type":"integer"},"minutes":{"type":"integer"}},"description":"Relative expiration for feedback tokens"}},"description":"Feedback options for the generated trace"}],"description":"Enable or configure feedback tokens for the trace"}},"description":"Optional generation parameters"}},"required":["input"]}}}},"responses":{"200":{"description":"Successfully generated text response from the agent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"anyOf":[{"type":"string","description":"Generated text response (legacy)"},{"type":"object","properties":{"text":{"type":"string"},"usage":{"type":"object","properties":{"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"reasoningTokens":{"type":"number"}},"required":["promptTokens","completionTokens","totalTokens"]},"finishReason":{"type":"string"},"toolCalls":{"type":"array","items":{"nullable":true}},"toolResults":{"type":"array","items":{"nullable":true}},"output":{"nullable":true,"description":"Structured output when output is used"},"feedback":{"type":"object","nullable":true,"properties":{"traceId":{"type":"string"},"key":{"type":"string"},"url":{"type":"string"},"tokenId":{"type":"string"},"expiresAt":{"type":"string"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"provided":{"type":"boolean"},"providedAt":{"type":"string"},"feedbackId":{"type":"string"}},"required":["traceId","key","url"],"description":"Feedback metadata for the trace"}},"required":["text"],"description":"AI SDK formatted response"}]}},"required":["success","data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to generate text due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/stream":{"post":{"tags":["Agent Generation"],"summary":"Stream raw text response","description":"Generate a text response from an agent and stream the raw fullStream data via Server-Sent Events (SSE). This endpoint provides direct access to all stream events including text deltas, tool calls, and tool results. Use this for advanced applications that need full control over stream processing.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"anyOf":[{"type":"string","description":"Direct text input"},{"type":"array","items":{"nullable":true},"description":"AI SDK message array (UIMessage or ModelMessage format)"}],"description":"Input text or messages array - accepts string, UIMessage[], or ModelMessage[]"},"options":{"type":"object","properties":{"memory":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation identifier for memory scoping"},"userId":{"type":"string","description":"User identifier for memory scoping"},"options":{"type":"object","properties":{"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of previous messages to include from memory"},"readOnly":{"type":"boolean","description":"When true, memory reads are allowed but no memory writes are persisted"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Semantic retrieval configuration for this call"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Per-call conversation persistence behavior"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Per-call persisted assistant message metadata behavior"}},"description":"Per-call memory behavior overrides"}},"description":"Runtime memory envelope (preferred): memory.userId/memory.conversationId + memory.options.*"},"userId":{"type":"string","description":"Deprecated: use options.memory.userId"},"conversationId":{"type":"string","description":"Deprecated: use options.memory.conversationId"},"context":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Deprecated: use options.memory.options.contextLimit"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Deprecated: use options.memory.options.semanticMemory"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Deprecated: use options.memory.options.conversationPersistence"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Deprecated: use options.memory.options.messageMetadataPersistence"},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Maximum number of steps for this request"},"temperature":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Controls randomness (0-1)"},"maxOutputTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":4000,"description":"Maximum tokens to generate"},"topP":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Controls diversity via nucleus sampling (0-1)"},"frequencyPenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes repeated tokens (0-2)"},"presencePenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes tokens based on presence (0-2)"},"seed":{"type":"integer","description":"Optional seed for reproducible results"},"stopSequences":{"type":"array","items":{"type":"string"},"description":"Stop sequences to end generation"},"providerOptions":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"},"resumableStream":{"type":"boolean","description":"When true, avoids wiring the HTTP abort signal into streams so they can be resumed (requires resumable streams and conversation/user IDs via options.memory or top-level legacy fields). If omitted, server defaults may apply."},"output":{"type":"object","properties":{"type":{"type":"string","enum":["object","text"],"description":"Output type: 'object' for structured JSON, 'text' for text-only output"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"JSON schema for structured output (required when type is 'object')"}},"required":["type"],"description":"Structured output configuration for schema-guided generation"},"feedback":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Feedback key for the trace"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"expiresAt":{"type":"string","description":"Absolute expiration timestamp (ISO 8601)"},"expiresIn":{"type":"object","properties":{"days":{"type":"integer"},"hours":{"type":"integer"},"minutes":{"type":"integer"}},"description":"Relative expiration for feedback tokens"}},"description":"Feedback options for the generated trace"}],"description":"Enable or configure feedback tokens for the trace"}},"description":"Optional generation parameters"}},"required":["input"]}}}},"responses":{"200":{"description":"Server-Sent Events stream with raw fullStream data. Each event is formatted as:\n'data: {\"type\":\"text-delta\",\"delta\":\"...\",\"id\":\"...\"}\n\n'\n\nor\n'data: {\"type\":\"tool-call\",\"toolName\":\"...\",\"args\":{...}}\n\n'\n\nor\n'data: {\"type\":\"tool-result\",\"toolName\":\"...\",\"result\":{...}}\n\n'\n\nor\n'data: {\"type\":\"finish\",\"finishReason\":\"...\",\"usage\":{...}}\n\n'","content":{"text/event-stream":{"schema":{"type":"object","properties":{"text":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["text","completion","error"]},"done":{"type":"boolean"},"error":{"type":"string"}}}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to stream text due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/chat":{"post":{"tags":["Agent Generation"],"summary":"Stream chat messages","description":"Generate a text response from an agent and stream it as UI messages via Server-Sent Events (SSE). This endpoint is optimized for chat interfaces and works seamlessly with the AI SDK's useChat hook. It provides a high-level stream format with automatic handling of messages, tool calls, and metadata.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"anyOf":[{"type":"string","description":"Direct text input"},{"type":"array","items":{"nullable":true},"description":"AI SDK message array (UIMessage or ModelMessage format)"}],"description":"Input text or messages array - accepts string, UIMessage[], or ModelMessage[]"},"options":{"type":"object","properties":{"memory":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation identifier for memory scoping"},"userId":{"type":"string","description":"User identifier for memory scoping"},"options":{"type":"object","properties":{"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of previous messages to include from memory"},"readOnly":{"type":"boolean","description":"When true, memory reads are allowed but no memory writes are persisted"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Semantic retrieval configuration for this call"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Per-call conversation persistence behavior"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Per-call persisted assistant message metadata behavior"}},"description":"Per-call memory behavior overrides"}},"description":"Runtime memory envelope (preferred): memory.userId/memory.conversationId + memory.options.*"},"userId":{"type":"string","description":"Deprecated: use options.memory.userId"},"conversationId":{"type":"string","description":"Deprecated: use options.memory.conversationId"},"context":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Deprecated: use options.memory.options.contextLimit"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Deprecated: use options.memory.options.semanticMemory"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Deprecated: use options.memory.options.conversationPersistence"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Deprecated: use options.memory.options.messageMetadataPersistence"},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Maximum number of steps for this request"},"temperature":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Controls randomness (0-1)"},"maxOutputTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":4000,"description":"Maximum tokens to generate"},"topP":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Controls diversity via nucleus sampling (0-1)"},"frequencyPenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes repeated tokens (0-2)"},"presencePenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes tokens based on presence (0-2)"},"seed":{"type":"integer","description":"Optional seed for reproducible results"},"stopSequences":{"type":"array","items":{"type":"string"},"description":"Stop sequences to end generation"},"providerOptions":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"},"resumableStream":{"type":"boolean","description":"When true, avoids wiring the HTTP abort signal into streams so they can be resumed (requires resumable streams and conversation/user IDs via options.memory or top-level legacy fields). If omitted, server defaults may apply."},"output":{"type":"object","properties":{"type":{"type":"string","enum":["object","text"],"description":"Output type: 'object' for structured JSON, 'text' for text-only output"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"JSON schema for structured output (required when type is 'object')"}},"required":["type"],"description":"Structured output configuration for schema-guided generation"},"feedback":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Feedback key for the trace"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"expiresAt":{"type":"string","description":"Absolute expiration timestamp (ISO 8601)"},"expiresIn":{"type":"object","properties":{"days":{"type":"integer"},"hours":{"type":"integer"},"minutes":{"type":"integer"}},"description":"Relative expiration for feedback tokens"}},"description":"Feedback options for the generated trace"}],"description":"Enable or configure feedback tokens for the trace"}},"description":"Optional generation parameters"}},"required":["input"]}}}},"responses":{"200":{"description":"Server-Sent Events stream formatted for useChat hook. UI message stream with automatic handling of messages, tool calls, and metadata.","content":{"text/event-stream":{"schema":{"type":"object","properties":{"text":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["text","completion","error"]},"done":{"type":"boolean"},"error":{"type":"string"}}}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to stream chat due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/chat/{conversationId}/stream":{"get":{"tags":["Agent Generation"],"summary":"Resume chat stream","description":"Resume an in-progress UI message stream for a chat conversation. Requires userId query parameter. Returns 204 if no active stream is found.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.conversationId"},"required":true,"name":"conversationId","in":"path"},{"schema":{"$ref":"#/components/schemas/QueryParam.userId"},"required":true,"name":"userId","in":"query"}],"responses":{"200":{"description":"Successfully resumed SSE stream for chat generation","content":{"text/event-stream":{"schema":{"type":"object","properties":{"text":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["text","completion","error"]},"done":{"type":"boolean"},"error":{"type":"string"}}}}}},"204":{"description":"No active stream found for the conversation","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Missing or invalid userId","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Resumable streams not configured","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to resume chat stream due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/object":{"post":{"tags":["Agent Generation"],"summary":"Generate structured object","description":"Generate a structured object that conforms to a specified JSON schema. This endpoint is perfect for extracting structured data from unstructured input, generating form data, or creating API responses with guaranteed structure. The agent will ensure the output matches the provided schema exactly.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"anyOf":[{"type":"string","description":"Direct text input"},{"type":"array","items":{"nullable":true},"description":"AI SDK message array (UIMessage or ModelMessage format)"}],"description":"Input text or messages array - accepts string, UIMessage[], or ModelMessage[]"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"The Zod schema for the desired object output (passed as JSON)"},"options":{"type":"object","properties":{"memory":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation identifier for memory scoping"},"userId":{"type":"string","description":"User identifier for memory scoping"},"options":{"type":"object","properties":{"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of previous messages to include from memory"},"readOnly":{"type":"boolean","description":"When true, memory reads are allowed but no memory writes are persisted"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Semantic retrieval configuration for this call"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Per-call conversation persistence behavior"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Per-call persisted assistant message metadata behavior"}},"description":"Per-call memory behavior overrides"}},"description":"Runtime memory envelope (preferred): memory.userId/memory.conversationId + memory.options.*"},"userId":{"type":"string","description":"Deprecated: use options.memory.userId"},"conversationId":{"type":"string","description":"Deprecated: use options.memory.conversationId"},"context":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Deprecated: use options.memory.options.contextLimit"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Deprecated: use options.memory.options.semanticMemory"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Deprecated: use options.memory.options.conversationPersistence"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Deprecated: use options.memory.options.messageMetadataPersistence"},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Maximum number of steps for this request"},"temperature":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Controls randomness (0-1)"},"maxOutputTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":4000,"description":"Maximum tokens to generate"},"topP":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Controls diversity via nucleus sampling (0-1)"},"frequencyPenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes repeated tokens (0-2)"},"presencePenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes tokens based on presence (0-2)"},"seed":{"type":"integer","description":"Optional seed for reproducible results"},"stopSequences":{"type":"array","items":{"type":"string"},"description":"Stop sequences to end generation"},"providerOptions":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"},"resumableStream":{"type":"boolean","description":"When true, avoids wiring the HTTP abort signal into streams so they can be resumed (requires resumable streams and conversation/user IDs via options.memory or top-level legacy fields). If omitted, server defaults may apply."},"output":{"type":"object","properties":{"type":{"type":"string","enum":["object","text"],"description":"Output type: 'object' for structured JSON, 'text' for text-only output"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"JSON schema for structured output (required when type is 'object')"}},"required":["type"],"description":"Structured output configuration for schema-guided generation"},"feedback":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Feedback key for the trace"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"expiresAt":{"type":"string","description":"Absolute expiration timestamp (ISO 8601)"},"expiresIn":{"type":"object","properties":{"days":{"type":"integer"},"hours":{"type":"integer"},"minutes":{"type":"integer"}},"description":"Relative expiration for feedback tokens"}},"description":"Feedback options for the generated trace"}],"description":"Enable or configure feedback tokens for the trace"}},"description":"Optional object generation parameters"}},"required":["input","schema"]}}}},"responses":{"200":{"description":"Successfully generated structured object matching the provided schema","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{},"description":"Generated object response"}},"required":["success","data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to generate object due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/stream-object":{"post":{"tags":["Agent Generation"],"summary":"Stream structured object generation","description":"Generate a structured object and stream partial updates via Server-Sent Events (SSE). This allows you to display incremental object construction in real-time, useful for complex object generation where you want to show progress. Events may contain partial object updates or the complete final object, depending on the agent's implementation.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"anyOf":[{"type":"string","description":"Direct text input"},{"type":"array","items":{"nullable":true},"description":"AI SDK message array (UIMessage or ModelMessage format)"}],"description":"Input text or messages array - accepts string, UIMessage[], or ModelMessage[]"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"The Zod schema for the desired object output (passed as JSON)"},"options":{"type":"object","properties":{"memory":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation identifier for memory scoping"},"userId":{"type":"string","description":"User identifier for memory scoping"},"options":{"type":"object","properties":{"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of previous messages to include from memory"},"readOnly":{"type":"boolean","description":"When true, memory reads are allowed but no memory writes are persisted"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Semantic retrieval configuration for this call"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Per-call conversation persistence behavior"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Per-call persisted assistant message metadata behavior"}},"description":"Per-call memory behavior overrides"}},"description":"Runtime memory envelope (preferred): memory.userId/memory.conversationId + memory.options.*"},"userId":{"type":"string","description":"Deprecated: use options.memory.userId"},"conversationId":{"type":"string","description":"Deprecated: use options.memory.conversationId"},"context":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Deprecated: use options.memory.options.contextLimit"},"semanticMemory":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable semantic retrieval for this call (default: auto when vectors are available)"},"semanticLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of similar messages to retrieve"},"semanticThreshold":{"type":"number","minimum":0,"maximum":1,"description":"Minimum similarity score (0-1)"},"mergeStrategy":{"type":"string","enum":["prepend","append","interleave"],"description":"How semantic results merge with recent history"}},"description":"Deprecated: use options.memory.options.semanticMemory"},"conversationPersistence":{"type":"object","properties":{"mode":{"type":"string","enum":["step","finish"],"description":"Persistence strategy: checkpoint by step or persist on finish"},"debounceMs":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Debounce window for step checkpoint persistence"},"flushOnToolResult":{"type":"boolean","description":"Flush immediately on tool-result/tool-error in step mode"}},"description":"Deprecated: use options.memory.options.conversationPersistence"},"messageMetadataPersistence":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"usage":{"type":"boolean","description":"Persist resolved token usage under message.metadata.usage"},"finishReason":{"type":"boolean","description":"Persist the final finish reason under message.metadata.finishReason"}}}],"description":"Deprecated: use options.memory.options.messageMetadataPersistence"},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Maximum number of steps for this request"},"temperature":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Controls randomness (0-1)"},"maxOutputTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":4000,"description":"Maximum tokens to generate"},"topP":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Controls diversity via nucleus sampling (0-1)"},"frequencyPenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes repeated tokens (0-2)"},"presencePenalty":{"type":"number","minimum":0,"maximum":2,"default":0,"description":"Penalizes tokens based on presence (0-2)"},"seed":{"type":"integer","description":"Optional seed for reproducible results"},"stopSequences":{"type":"array","items":{"type":"string"},"description":"Stop sequences to end generation"},"providerOptions":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"},"resumableStream":{"type":"boolean","description":"When true, avoids wiring the HTTP abort signal into streams so they can be resumed (requires resumable streams and conversation/user IDs via options.memory or top-level legacy fields). If omitted, server defaults may apply."},"output":{"type":"object","properties":{"type":{"type":"string","enum":["object","text"],"description":"Output type: 'object' for structured JSON, 'text' for text-only output"},"schema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"A dictionary defining each property of the object and its type"},"required":{"type":"array","items":{"type":"string"},"description":"List of required property names in the object"}},"required":["type"],"description":"JSON schema for structured output (required when type is 'object')"}},"required":["type"],"description":"Structured output configuration for schema-guided generation"},"feedback":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Feedback key for the trace"},"feedbackConfig":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["continuous","categorical","freeform"]},"min":{"type":"number"},"max":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"description":{"type":"string"}},"required":["value"]}}},"required":["type"],"description":"Feedback configuration for the trace"},"expiresAt":{"type":"string","description":"Absolute expiration timestamp (ISO 8601)"},"expiresIn":{"type":"object","properties":{"days":{"type":"integer"},"hours":{"type":"integer"},"minutes":{"type":"integer"}},"description":"Relative expiration for feedback tokens"}},"description":"Feedback options for the generated trace"}],"description":"Enable or configure feedback tokens for the trace"}},"description":"Optional object generation parameters"}},"required":["input","schema"]}}}},"responses":{"200":{"description":"Server-Sent Events stream for object generation.\nEvents might contain partial object updates or the final object.\nThe exact format (e.g., JSON patches, partial objects) depends on the agent's implementation.\nExample event: 'data: {\"partialUpdate\": {...}}\n\n' or 'data: {\"finalObject\": {...}}\n\n'","content":{"text/event-stream":{"schema":{"nullable":true,"description":"Streamed object parts or the final object"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to stream object due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/workspace":{"get":{"tags":["Agent Workspace"],"summary":"Get agent workspace info","description":"Retrieve workspace configuration metadata for an agent, including capabilities (filesystem, sandbox, search, skills).","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Successfully retrieved workspace info","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","description":"Workspace ID"},"name":{"type":"string","description":"Workspace name"},"scope":{"type":"string","enum":["agent","conversation"],"description":"Workspace scope"},"capabilities":{"type":"object","properties":{"filesystem":{"type":"boolean","description":"Filesystem access enabled"},"sandbox":{"type":"boolean","description":"Sandbox execution enabled"},"search":{"type":"boolean","description":"Search enabled"},"skills":{"type":"boolean","description":"Skills enabled"}},"required":["filesystem","sandbox","search","skills"]}},"required":["id","capabilities"]}},"required":["success","data"]}}}},"404":{"description":"Agent or workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to retrieve workspace info due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/workspace/ls":{"get":{"tags":["Agent Workspace"],"summary":"List workspace files","description":"List files and directories under a workspace path.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Workspace path to list"},"required":false,"description":"Workspace path to list","name":"path","in":"query"}],"responses":{"200":{"description":"Successfully listed workspace files","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"path":{"type":"string"},"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"is_dir":{"type":"boolean"},"size":{"type":"number"},"modified_at":{"type":"string"}},"required":["path","is_dir"]}}},"required":["path","entries"]}},"required":["success","data"]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Agent or workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to list workspace files due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/workspace/read":{"get":{"tags":["Agent Workspace"],"summary":"Read workspace file","description":"Read a file from the workspace filesystem.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"File path to read"},"required":true,"description":"File path to read","name":"path","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Line offset (0-indexed)"},"required":false,"description":"Line offset (0-indexed)","name":"offset","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Max lines to read"},"required":false,"description":"Max lines to read","name":"limit","in":"query"}],"responses":{"200":{"description":"Successfully read workspace file","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"}},"required":["path","content"]}},"required":["success","data"]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Agent or workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to read workspace file due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/workspace/skills":{"get":{"tags":["Agent Workspace"],"summary":"List workspace skills","description":"List available workspace skills for an agent.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"boolean","nullable":true,"description":"Refresh skill discovery"},"required":false,"description":"Refresh skill discovery","name":"refresh","in":"query"}],"responses":{"200":{"description":"Successfully listed workspace skills","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"path":{"type":"string"},"root":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"scripts":{"type":"array","items":{"type":"string"}},"assets":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean","description":"Whether the skill is currently activated"}},"required":["id","name","path","root","active"]}}},"required":["skills"]}},"required":["success","data"]}}}},"404":{"description":"Agent, workspace, or skills not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to list workspace skills due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/agents/{id}/workspace/skills/{skillId}":{"get":{"tags":["Agent Workspace"],"summary":"Get workspace skill","description":"Retrieve a specific workspace skill including its instructions.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"description":"Skill identifier","name":"skillId","in":"path"}],"responses":{"200":{"description":"Successfully retrieved workspace skill","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"path":{"type":"string"},"root":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"scripts":{"type":"array","items":{"type":"string"}},"assets":{"type":"array","items":{"type":"string"}},"instructions":{"type":"string"}},"required":["id","name","path","root","instructions"]}},"required":["success","data"]}}}},"404":{"description":"Agent, workspace, or skill not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to retrieve workspace skill due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows":{"get":{"tags":["Workflow Management"],"summary":"List all registered workflows","description":"Retrieve a list of all workflows registered in the system. Each workflow includes its ID, name, purpose, step count, and current status. Use this endpoint to discover available workflows and understand their capabilities before execution.","responses":{"200":{"description":"Successfully retrieved list of all registered workflows","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique workflow identifier"},"name":{"type":"string","description":"Human-readable workflow name"},"purpose":{"type":"string","description":"Description of what the workflow does"},"stepsCount":{"type":"integer","description":"Number of steps in the workflow"},"status":{"type":"string","enum":["idle","running","completed","error"],"description":"Current status of the workflow"}},"required":["id","name","purpose","stepsCount","status"]},"description":"Array of workflow objects with their configurations"}},"required":["success","data"]}}}},"500":{"description":"Failed to retrieve workflows due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/execute":{"post":{"tags":["Workflow Management"],"summary":"Execute workflow synchronously","description":"Execute a workflow and wait for it to complete. This endpoint runs the workflow to completion and returns the final result. Use this for workflows that complete quickly or when you need the complete result before proceeding. For long-running workflows, consider using the streaming endpoint instead.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"nullable":true,"description":"Input data for the workflow"},"options":{"type":"object","properties":{"userId":{"type":"string"},"conversationId":{"type":"string"},"executionId":{"type":"string"},"context":{"nullable":true},"workflowState":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"description":"Optional execution options"}}}}}},"responses":{"200":{"description":"Successfully executed workflow and returned final result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"executionId":{"type":"string"},"startAt":{"type":"string"},"endAt":{"type":"string"},"status":{"type":"string","enum":["completed"]},"result":{"nullable":true}},"required":["executionId","startAt","endAt","status"],"description":"Workflow execution result"}},"required":["success","data"]}}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to execute workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/stream":{"post":{"tags":["Workflow Management"],"summary":"Stream workflow execution events","description":"Execute a workflow and stream real-time events via Server-Sent Events (SSE). The stream remains open during suspension and continues after resume.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"nullable":true,"description":"Input data for the workflow"},"options":{"type":"object","properties":{"userId":{"type":"string"},"conversationId":{"type":"string"},"executionId":{"type":"string"},"context":{"nullable":true},"workflowState":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"description":"Optional execution options"}}}}}},"responses":{"200":{"description":"Server-Sent Events stream for workflow execution.\nEach event is formatted as:\n'data: {\"type\":\"step-start\", \"executionId\":\"...\", \"from\":\"...\", ...}\\n\\n'\n\nEvent types include:\n- workflow-start: Workflow execution started\n- step-start: Step execution started\n- step-complete: Step completed successfully\n- workflow-suspended: Workflow suspended, awaiting resume\n- workflow-cancelled: Workflow cancelled by client request\n- workflow-complete: Workflow completed successfully\n- workflow-error: Workflow encountered an error\n- Custom events from step writers","content":{"text/event-stream":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Event type"},"executionId":{"type":"string","description":"Workflow execution ID"},"from":{"type":"string","description":"Source of the event"},"input":{"nullable":true},"output":{"nullable":true},"status":{"type":"string","enum":["pending","running","success","error","suspended","cancelled"]},"timestamp":{"type":"string"},"stepIndex":{"type":"number"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"nullable":true}},"required":["type","executionId","from","status","timestamp"]}}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to stream workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/executions/{executionId}/stream":{"get":{"tags":["Workflow Management"],"summary":"Attach to workflow execution stream","description":"Attach to an in-progress workflow execution stream and receive real-time events via Server-Sent Events (SSE). Use Last-Event-ID header or `fromSequence` query parameter to replay missed events on reconnect.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.executionId"},"required":true,"name":"executionId","in":"path"},{"schema":{"type":"string","description":"Replay events with sequence greater than this value"},"required":false,"description":"Replay events with sequence greater than this value","name":"fromSequence","in":"query"}],"responses":{"200":{"description":"Server-Sent Events stream for an existing workflow execution.\nEach event includes SSE id for replay/reconnect support:\n'id: 42\\n'\n'data: {\"type\":\"step-start\",\"executionId\":\"...\", ...}\\n\\n'","content":{"text/event-stream":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Event type"},"executionId":{"type":"string","description":"Workflow execution ID"},"from":{"type":"string","description":"Source of the event"},"input":{"nullable":true},"output":{"nullable":true},"status":{"type":"string","enum":["pending","running","success","error","suspended","cancelled"]},"timestamp":{"type":"string"},"stepIndex":{"type":"number"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"nullable":true}},"required":["type","executionId","from","status","timestamp"]}}}},"404":{"description":"Workflow or execution not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"409":{"description":"Workflow execution is not streamable in current state","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to attach workflow stream due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/executions/{executionId}/suspend":{"post":{"tags":["Workflow Management"],"summary":"Suspend workflow execution","description":"Suspend a running workflow execution at its current step. This allows you to pause long-running workflows, perform external validations, wait for human approval, or handle rate limits. The workflow state is preserved and can be resumed later with the resume endpoint. Only workflows in 'running' state can be suspended.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.executionId"},"required":true,"name":"executionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for suspension"}}}}}},"responses":{"200":{"description":"Successfully suspended workflow execution","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"executionId":{"type":"string"},"status":{"type":"string","enum":["suspended"]},"suspension":{"type":"object","properties":{"suspendedAt":{"type":"string"},"reason":{"type":"string"}},"required":["suspendedAt"]}},"required":["executionId","status","suspension"],"description":"Workflow suspension result"}},"required":["success","data"]}}}},"400":{"description":"Workflow is not in a suspendable state","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Workflow or execution not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to suspend workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/executions/{executionId}/cancel":{"post":{"tags":["Workflow Management"],"summary":"Cancel workflow execution","description":"Cancel a running workflow execution immediately. The workflow stops execution and the state is marked as cancelled. Cancelled workflows cannot be resumed.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.executionId"},"required":true,"name":"executionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for cancellation"}}}}}},"responses":{"200":{"description":"Successfully cancelled workflow execution","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"executionId":{"type":"string"},"status":{"type":"string","enum":["cancelled"]},"cancelledAt":{"type":"string"},"reason":{"type":"string"}},"required":["executionId","status","cancelledAt"],"description":"Workflow cancellation result"}},"required":["success","data"]}}}},"404":{"description":"Workflow or execution not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"409":{"description":"Workflow execution already completed or not cancellable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to cancel workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/executions/{executionId}/resume":{"post":{"tags":["Workflow Management"],"summary":"Resume suspended workflow","description":"Resume a previously suspended workflow execution from where it left off. You can optionally provide resume data that will be passed to the suspended step for processing. This is commonly used after human approval, external system responses, or scheduled resumptions. The workflow continues execution and returns the final result.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.executionId"},"required":true,"name":"executionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resumeData":{"nullable":true,"description":"Data to pass to the resumed step (validated against step's resumeSchema)"},"options":{"type":"object","properties":{"stepId":{"type":"string","description":"Optional step ID to resume from a specific step instead of the suspended one"}},"description":"Optional resume options"}}}}}},"responses":{"200":{"description":"Successfully resumed workflow execution and returned final result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"executionId":{"type":"string"},"startAt":{"type":"string"},"endAt":{"type":"string"},"status":{"type":"string"},"result":{"nullable":true}},"required":["executionId","startAt","status"],"description":"Workflow resume result"}},"required":["success","data"]}}}},"404":{"description":"Workflow or execution not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to resume workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/workflows/{id}/executions/{executionId}/replay":{"post":{"tags":["Workflow Management"],"summary":"Replay workflow execution from a step","description":"Create a deterministic replay execution from a historical workflow run and selected step. Replay creates a new execution ID and preserves the original run history.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/PathParam.id"},{"description":"The ID of the workflow","example":"my-workflow-123"}]},"required":true,"name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/PathParam.executionId"},"required":true,"name":"executionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stepId":{"type":"string","minLength":1,"description":"Step ID to replay from"},"inputData":{"nullable":true,"description":"Optional input override for the selected step"},"resumeData":{"nullable":true,"description":"Optional resume payload override"},"workflowStateOverride":{"type":"object","additionalProperties":{"nullable":true},"description":"Optional workflow state override for replay run"}},"required":["stepId"]}}}},"responses":{"200":{"description":"Successfully replayed workflow execution","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"executionId":{"type":"string"},"startAt":{"type":"string"},"endAt":{"type":"string"},"status":{"type":"string"},"result":{"nullable":true}},"required":["executionId","startAt","status"],"description":"Workflow replay result"}},"required":["success","data"]}}}},"400":{"description":"Invalid replay parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Workflow or source execution not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to replay workflow due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/tools":{"get":{"tags":["Tools"],"summary":"List all tools","description":"Retrieve a list of all tools registered across agents. Includes name, description, parameters, and owning agent metadata.","responses":{"200":{"description":"Successfully retrieved list of tools","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string"},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id"]}},"tags":{"type":"array","items":{"type":"string"}}},"required":["name"]}}},"required":["success","data"]}}}},"500":{"description":"Failed to retrieve tools due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/tools/{name}/execute":{"post":{"tags":["Tools"],"summary":"Execute a tool directly","description":"Execute a registered tool directly via HTTP without going through the agent chat flow. Accepts tool input and optional context metadata.","parameters":[{"schema":{"$ref":"#/components/schemas/PathParam.name"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"nullable":true},"context":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"userId":{"type":"string"},"conversationId":{"type":"string"}},"default":{"input":{},"context":{}}}}}},"responses":{"200":{"description":"Successfully executed tool","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"toolName":{"type":"string"},"agentId":{"type":"string"},"result":{"nullable":true},"executionTime":{"type":"number"},"timestamp":{"type":"string"}},"required":["toolName"]}},"required":["success","data"]}}}},"400":{"description":"Invalid request or tool input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}},"500":{"description":"Failed to execute tool due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/api/logs":{"get":{"tags":["Logging"],"summary":"Get logs with filters","description":"Retrieve system logs with optional filtering by level, agent ID, workflow ID, conversation ID, execution ID, and time range.","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000,"default":100,"description":"Maximum number of log entries to return","example":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["trace","debug","info","warn","error","fatal"],"description":"Minimum log level to filter by","example":"info"},"required":false,"name":"level","in":"query"},{"schema":{"type":"string","description":"Filter logs by agent ID","example":"agent-123"},"required":false,"name":"agentId","in":"query"},{"schema":{"type":"string","description":"Filter logs by conversation ID","example":"conv-456"},"required":false,"name":"conversationId","in":"query"},{"schema":{"type":"string","description":"Filter logs by workflow ID","example":"workflow-789"},"required":false,"name":"workflowId","in":"query"},{"schema":{"type":"string","description":"Filter logs by workflow execution ID","example":"exec-012"},"required":false,"name":"executionId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return logs since this timestamp (ISO 8601)","example":"2024-01-01T00:00:00Z"},"required":false,"name":"since","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return logs until this timestamp (ISO 8601)","example":"2024-01-01T23:59:59Z"},"required":false,"name":"until","in":"query"}],"responses":{"200":{"description":"Successfully retrieved filtered log entries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"level":{"type":"string","enum":["trace","debug","info","warn","error","fatal","silent"]},"msg":{"type":"string"},"component":{"type":"string"},"agentId":{"type":"string"},"conversationId":{"type":"string"},"workflowId":{"type":"string"},"executionId":{"type":"string"},"userId":{"type":"string"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"stack":{"type":"string"}},"required":["type","message"]}},"required":["timestamp","level","msg"],"additionalProperties":{"nullable":true}}},"total":{"type":"integer"},"query":{"type":"object","properties":{"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000,"default":100,"description":"Maximum number of log entries to return","example":100},"level":{"type":"string","enum":["trace","debug","info","warn","error","fatal"],"description":"Minimum log level to filter by","example":"info"},"agentId":{"type":"string","description":"Filter logs by agent ID","example":"agent-123"},"conversationId":{"type":"string","description":"Filter logs by conversation ID","example":"conv-456"},"workflowId":{"type":"string","description":"Filter logs by workflow ID","example":"workflow-789"},"executionId":{"type":"string","description":"Filter logs by workflow execution ID","example":"exec-012"},"since":{"type":"string","format":"date-time","description":"Return logs since this timestamp (ISO 8601)","example":"2024-01-01T00:00:00Z"},"until":{"type":"string","format":"date-time","description":"Return logs until this timestamp (ISO 8601)","example":"2024-01-01T23:59:59Z"}}}},"required":["success","data","total","query"]}}}},"500":{"description":"Failed to retrieve logs due to server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Error message"}},"required":["success","error"]}}}}}}},"/*":{"all":{"tags":["Custom Endpoints"],"summary":"ALL /*","description":"Custom endpoint: ALL /*","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}}}}}}}