{"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:3141","description":"Local development server"}],"components":{"schemas":{},"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":{"type":"string","description":"The ID of the agent","example":"my-agent-123"},"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":{"userId":{"type":"string","description":"Optional user ID for context tracking"},"conversationId":{"type":"string","description":"Optional conversation ID for context tracking"},"context":{"type":"object","additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Optional limit for conversation history context"},"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","additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"}},"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}}},"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":{"type":"string","description":"The ID of the agent","example":"my-agent-123"},"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":{"userId":{"type":"string","description":"Optional user ID for context tracking"},"conversationId":{"type":"string","description":"Optional conversation ID for context tracking"},"context":{"type":"object","additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Optional limit for conversation history context"},"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","additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"}},"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":{"type":"string","description":"The ID of the agent","example":"my-agent-123"},"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":{"userId":{"type":"string","description":"Optional user ID for context tracking"},"conversationId":{"type":"string","description":"Optional conversation ID for context tracking"},"context":{"type":"object","additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Optional limit for conversation history context"},"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","additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"}},"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}/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":{"type":"string","description":"The ID of the agent","example":"my-agent-123"},"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","additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","number","boolean","object","array","null","any"]}},"required":["type"]},"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":{"userId":{"type":"string","description":"Optional user ID for context tracking"},"conversationId":{"type":"string","description":"Optional conversation ID for context tracking"},"context":{"type":"object","additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Optional limit for conversation history context"},"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","additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"}},"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":{"type":"string","description":"The ID of the agent","example":"my-agent-123"},"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","additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","number","boolean","object","array","null","any"]}},"required":["type"]},"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":{"userId":{"type":"string","description":"Optional user ID for context tracking"},"conversationId":{"type":"string","description":"Optional conversation ID for context tracking"},"context":{"type":"object","additionalProperties":{"nullable":true},"description":"User context for dynamic agent behavior"},"contextLimit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":10,"description":"Optional limit for conversation history context"},"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","additionalProperties":{"nullable":true},"description":"Provider-specific options for AI SDK providers (e.g., OpenAI's reasoningEffort)"}},"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"]}}}}}}},"/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":{"type":"string","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"},"context":{"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":{"type":"string","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"},"context":{"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-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"]},"timestamp":{"type":"string"},"stepIndex":{"type":"number"},"metadata":{"type":"object","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}/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":{"type":"string","description":"The ID of the workflow","example":"my-workflow-123"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The ID of the execution to operate on","example":"exec_1234567890_abc123"},"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}/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":{"type":"string","description":"The ID of the workflow","example":"my-workflow-123"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The ID of the execution to operate on","example":"exec_1234567890_abc123"},"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"]}}}}}}},"/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"]}}}}}}}}}