openapi: 3.0.3 info: title: Ask Sage Server Admin Execute Agent API description: 'Ask Sage is an AI-powered platform providing intelligent completions, knowledge management, and workflow automation. ## Base URL `https://api.asksage.ai` ## Authentication All endpoints require a valid JWT token passed via the `x-access-tokens` header, unless otherwise noted. Obtain a token by authenticating through the User API (`/user/get-token-with-api-key`). ## Message Format The `message` field in API requests can be either: - A single string prompt: `"What is Ask Sage?"` - An array of conversation messages: `[{"user": "me", "message": "what is Ask Sage?"}, {"user": "gpt", "message": "Ask Sage is an..."}]` ## Key Features - **AI Completions** — Query multiple LLM providers with a unified interface - **Knowledge Training** — Upload documents, files, and data to build custom datasets - **Tabular Data** — Ingest and query structured data (CSV, XLSX) with natural language - **Agent Builder** — Create, configure, and execute multi-step AI workflows - **Plugins** — Extend capabilities with built-in and custom plugins - **MCP Servers** — Connect to Model Context Protocol servers for tool integration' version: '2.0' contact: name: Ask Sage Support email: support@asksage.ai url: https://asksage.ai servers: - url: '{baseUrl}/server' description: Ask Sage Server API variables: baseUrl: default: https://api.asksage.ai description: API base URL. Use https://api.asksage.ai for production, or your self-hosted instance URL. security: - ApiKeyAuth: [] tags: - name: Execute Agent paths: /execute-agent: post: summary: Execute Agent description: 'Executes a specific agent with a message and optional parameters. Supports both non-streaming (JSON) and streaming (Server-Sent Events) responses. ' operationId: execute_agent_ep requestBody: required: true content: application/json: schema: type: object required: - agent_id - message properties: agent_id: type: integer description: ID of the agent to execute. message: type: string description: The user's message/prompt to the agent. streaming: type: boolean description: If true, enables a Server-Sent Events (SSE) stream. If false, returns a single JSON response. default: true variables: type: object description: A JSON object of runtime variables. For file variables, the value should be the filename of a file uploaded via a multipart/form-data request. example: priority: high source_data: data.csv conversation_history: type: array description: A JSON array representing the conversation history. items: type: object properties: message: type: string user: type: string enum: - me - system multipart/form-data: schema: type: object required: - agent_id - message properties: agent_id: type: integer message: type: string streaming: type: string enum: - 'true' - 'false' default: 'true' variables: type: string description: A JSON string of runtime variables. The value for a file variable must match the filename of an uploaded file. example: '{"priority": "high", "source_data": "data.csv"}' conversation_history: type: string description: A JSON string of the conversation history array. file: type: string format: binary description: A file to be processed. To upload multiple files, provide multiple form parts with the same 'file' key. responses: '200': description: 'Agent execution initiated. The response format depends on the `streaming` parameter and the `Accept` header. ' content: application/json: schema: $ref: '#/components/schemas/AgentExecutionResponse' text/plain: schema: type: string description: 'A Server-Sent Events (SSE) stream, sent when `streaming: true`. The stream consists of multiple JSON objects, each preceded by `data: ` and followed by `\n\n`. **Event Types:** Each JSON object has an `event` field. Key events include: - `workflow_started`: Signals the beginning of execution. - `node_completed`: A node finished successfully. Contains `data.output`. - `node_error`: A node failed. Contains `data.error`. - `workflow_completed`: The workflow finished. Contains final `data.output`. - `agent_response`: The final, processed response from the agent. **Example Event:** `data: {"event": "node_completed", "data": {"node_id": "llm_1", "output": {"response": "Hello!"}}, "timestamp": "..."}\n\n` ' '400': description: Bad request - check agent_id and variables. content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Agent not found. content: application/json: schema: $ref: '#/components/schemas/ApiError' '413': description: Request payload too large. content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Execution error - see error field for details. content: application/json: schema: $ref: '#/components/schemas/ExecutionError' '504': description: Timeout - agent execution took too long. content: application/json: schema: $ref: '#/components/schemas/ExecutionError' tags: - Execute Agent components: schemas: ExecutionError: type: object properties: error: type: string message: type: string details: type: string ApiError: type: object properties: error: type: string description: Error message status: type: integer description: HTTP status code details: type: string description: Additional error details required: - error AgentExecutionResponse: type: object properties: status: type: integer description: HTTP status code example: 200 execution_status: type: string enum: - completed - failed - timeout description: Status of the agent execution execution_id: type: integer description: Unique identifier for this execution duration_ms: type: integer description: Execution duration in milliseconds response: type: object properties: response: type: string description: The agent's final response text type: type: string description: Type of response (e.g., "text") source: type: string description: Source node of the response workflow: type: object description: Details of the primary workflow that was executed properties: id: type: integer description: The workflow's numeric ID uuid: type: string format: uuid description: The workflow's unique identifier name: type: string description: The name of the workflow version: type: integer description: The version number of the workflow that was executed node_executions: type: array description: A step-by-step log of each node's execution within the workflow items: type: object properties: node_id: type: string description: The unique identifier of the node node_type: type: string description: The type of node (e.g., "llm", "condition") status: type: string enum: - completed - failed description: The execution status of the node output: type: object nullable: true description: The output produced by the node if successful error: type: object nullable: true description: Error details if the node failed metadata: type: object nullable: true description: Additional metadata about the node execution error: type: string nullable: true description: Error message if execution failed securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-access-tokens description: JWT authentication token. Obtain a token by calling the User API endpoint `/user/get-token-with-api-key` with your email and API key.