Core AI operations for the Ask Sage platform — available models, query and completions (incl. with files), agents, plugins, Deep Agent, datasets and training, tokenizer, usage/token metering, text-to-speech, and MCP server management.
{
"openapi": "3.0.3",
"info": {
"title": "Ask Sage Server API",
"description": "Ask Sage is an AI-powered platform providing intelligent completions, knowledge management, and workflow automation.\n\n## Base URL\n`https://api.asksage.ai`\n\n## Authentication\nAll endpoints require a valid JWT token passed via the `x-access-tokens` header, unless otherwise noted.\n\nObtain a token by authenticating through the User API (`/user/get-token-with-api-key`).\n\n## Message Format\nThe `message` field in API requests can be either:\n- A single string prompt: `\"What is Ask Sage?\"`\n- An array of conversation messages: `[{\"user\": \"me\", \"message\": \"what is Ask Sage?\"}, {\"user\": \"gpt\", \"message\": \"Ask Sage is an...\"}]`\n\n## Key Features\n- **AI Completions** \u2014 Query multiple LLM providers with a unified interface\n- **Knowledge Training** \u2014 Upload documents, files, and data to build custom datasets\n- **Tabular Data** \u2014 Ingest and query structured data (CSV, XLSX) with natural language\n- **Agent Builder** \u2014 Create, configure, and execute multi-step AI workflows\n- **Plugins** \u2014 Extend capabilities with built-in and custom plugins\n- **MCP Servers** \u2014 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": []
}
],
"components": {
"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."
}
},
"schemas": {
"Message": {
"oneOf": [
{
"type": "string",
"description": "Single message prompt",
"example": "What is Ask Sage?"
},
{
"type": "array",
"description": "Array of conversation messages",
"items": {
"type": "object",
"required": [
"user",
"message"
],
"properties": {
"user": {
"type": "string",
"enum": [
"me",
"gpt"
],
"description": "Identifies the sender of the message"
},
"message": {
"type": "string",
"description": "The content of the message"
}
}
},
"example": [
{
"user": "me",
"message": "What is Ask Sage?"
},
{
"user": "gpt",
"message": "Ask Sage is an..."
}
]
}
]
},
"Tool": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the tool/function"
},
"description": {
"type": "string",
"description": "Description of what the tool does"
},
"parameters": {
"type": "object",
"description": "Parameters schema for the tool"
}
}
},
"ToolChoice": {
"oneOf": [
{
"type": "string",
"enum": [
"auto",
"none",
"required"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"function"
]
},
"function": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
}
}
}
]
},
"CompletionResponse": {
"type": "object",
"properties": {
"response": {
"type": "string",
"description": "Status message or error description"
},
"message": {
"type": "string",
"description": "Generated completion text"
},
"embedding_down": {
"type": "boolean",
"description": "Whether embedding service is down"
},
"vectors_down": {
"type": "boolean",
"description": "Whether vector database is down"
},
"uuid": {
"type": "string",
"description": "Unique identifier for this completion"
},
"references": {
"type": "string",
"description": "References used for the completion"
},
"type": {
"type": "string",
"description": "Type of response"
},
"added_obj": {
"type": "object",
"nullable": true,
"description": "Additional object data for chained operations"
},
"tool_calls": {
"type": "array",
"nullable": true,
"description": "Tool/function calls made during completion"
},
"usage": {
"type": "object",
"nullable": true,
"description": "Token usage statistics"
},
"tool_responses": {
"type": "array",
"nullable": true,
"description": "Responses from tool executions"
},
"tool_calls_unified": {
"type": "array",
"nullable": true,
"description": "Unified tool calls format"
},
"status": {
"type": "integer",
"description": "HTTP status code"
}
}
},
"MCPServer": {
"type": "object",
"required": [
"server_name",
"server_url"
],
"properties": {
"server_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9\\s\\-_.]+$",
"description": "Name of the MCP server"
},
"server_url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "HTTPS URL of the MCP server"
},
"server_type": {
"type": "string",
"maxLength": 50,
"pattern": "^[a-zA-Z0-9\\-_]+$",
"description": "Type of MCP server"
},
"description": {
"type": "string",
"maxLength": 1000,
"description": "Description of the MCP server"
},
"metadata_json": {
"type": "string",
"description": "Additional metadata in JSON format"
}
}
},
"Agent": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the agent"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "The unique identifier for the agent resource"
},
"name": {
"type": "string",
"description": "Name of the agent"
},
"description": {
"type": "string",
"description": "A brief description of the agent's purpose"
},
"agent_mode": {
"type": "string",
"enum": [
"single",
"router",
"autonomous"
],
"description": "Agent execution mode"
},
"current_version": {
"type": "integer",
"description": "Current version number of the agent"
},
"is_published": {
"type": "boolean",
"description": "Indicates if the current version is published and available for use"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the agent was created"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the agent was last updated"
},
"primary_workflow_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the primary workflow"
}
}
},
"ConversationMessage": {
"type": "object",
"required": [
"message",
"user"
],
"properties": {
"message": {
"type": "string",
"description": "The content of the message"
},
"user": {
"type": "string",
"enum": [
"me",
"system"
],
"description": "Identifies the sender (me = user, system = agent)"
}
}
},
"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"
}
}
},
"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"
]
},
"ExecutionError": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "string"
}
}
}
}
},
"paths": {
"/get-models": {
"get": {
"summary": "Get available models",
"description": "Returns a list of all available AI models",
"security": [],
"tags": [
"Models"
],
"responses": {
"200": {
"description": "List of available models",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "array",
"items": {
"type": "string"
}
},
"object": {
"type": "string",
"example": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"example": "model"
},
"created": {
"type": "string"
},
"name": {
"type": "string"
},
"owned_by": {
"type": "string"
}
}
}
},
"status": {
"type": "integer",
"example": 200
}
}
}
}
}
}
}
},
"post": {
"summary": "Get available models",
"description": "Returns a list of all available AI models",
"security": [],
"tags": [
"Models"
],
"responses": {
"200": {
"description": "List of available models",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "array",
"items": {
"type": "string"
}
},
"object": {
"type": "string",
"example": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"example": "model"
},
"created": {
"type": "string"
},
"name": {
"type": "string"
},
"owned_by": {
"type": "string"
}
}
}
},
"status": {
"type": "integer",
"example": 200
}
}
}
}
}
}
}
}
},
"/query": {
"post": {
"summary": "Generate completion",
"description": "Main endpoint for generating AI completions. \nThe message field can be either a string or an array of conversation messages.\n",
"tags": [
"Completions"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"$ref": "#/components/schemas/Message"
},
"persona": {
"type": "integer",
"description": "Persona ID to use for the completion",
"default": 1
},
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tool"
},
"description": "Available tools/functions for the model to use"
},
"enabled_mcp_tools": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of enabled MCP tools"
},
"tools_to_execute": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific tools to execute"
},
"tool_choice": {
"$ref": "#/components/schemas/ToolChoice"
},
"reasoning_effort": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Reasoning effort level for o1/o3 models"
},
"system_prompt": {
"type": "string",
"description": "Custom system prompt to override persona"
},
"mode": {
"type": "string",
"enum": [
"chat",
"deep_agent"
],
"default": "chat",
"description": "Completion mode"
},
"deep_agent_id": {
"type": "integer",
"description": "Deep agent ID for deep_agent mode"
},
"dataset": {
"oneOf": [
{
"type": "string",
"description": "Single dataset name or 'all'/'none'"
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "Multiple dataset names"
}
],
"default": "all"
},
"limit_references": {
"type": "integer",
"enum": [
0,
1
],
"description": "Limit number of references (0=none, 1=limited)"
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0,
"description": "Sampling temperature"
},
"model": {
"type": "string",
"description": "Model to use for completion",
"example": "gpt-4.1-mini"
},
"live": {
"type": "integer",
"enum": [
0,
1,
2
],
"default": 0,
"description": "Live search mode (0=off, 1=basic, 2=advanced)"
},
"streaming": {
"type": "boolean",
"default": false,
"description": "Enable streaming response"
},
"usage": {
"type": "boolean",
"description": "Include usage statistics in response"
},
"timezone": {
"type": "string",
"description": "Timezone for time-related queries"
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "Message as JSON string. Can be either:\n- A single string prompt: `\"What is Ask Sage?\"`\n- An array of conversation messages: `[{\"user\": \"me\", \"message\": \"What is Ask Sage?\"}, {\"user\": \"gpt\", \"message\": \"Ask Sage is...\"}]`\n\nWhen sending via form data, the message must be JSON-encoded.\n",
"example": "[{\"user\": \"me\", \"message\": \"What is Ask Sage?\"}, {\"user\": \"gpt\", \"message\": \"Ask Sage is an AI platform...\"}]"
},
"persona": {
"type": "string"
},
"tools": {
"type": "string",
"description": "Tools as JSON string"
},
"enabled_mcp_tools": {
"type": "string",
"description": "Enabled MCP tools as JSON string"
},
"tools_to_execute": {
"type": "string",
"description": "Tools to execute as JSON string"
},
"tool_choice": {
"type": "string",
"description": "Tool choice as JSON string"
},
"reasoning_effort": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"mode": {
"type": "string"
},
"deep_agent_id": {
"type": "string"
},
"dataset": {
"type": "string"
},
"limit_references": {
"type": "string"
},
"temperature": {
"type": "string"
},
"model": {
"type": "string"
},
"live": {
"type": "string"
},
"streaming": {
"type": "string"
},
"usage": {
"type": "string"
},
"timezone": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful completion",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompletionResponse"
}
},
"text/plain": {
"schema": {
"type": "string",
"description": "Streaming response with delimiter-separated JSON chunks"
}
}
}
}
}
}
},
"/query_with_file": {
"post": {
"summary": "Generate completion with file attachments",
"description": "Generate AI completion with one or more file attachments. Supports multiple files.\nMaximum file size: 500MB per file. Maximum number of files determined by server configuration.\n",
"tags": [
"Completions"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"message"
],
"properties": {
"file": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"description": "One or more files to process with the query"
},
"message": {
"type": "string",
"description": "Message as JSON string. Can be either:\n- A single string prompt: `\"What is Ask Sage?\"`\n- An array of conversation messages: `[{\"user\": \"me\", \"message\": \"What is Ask Sage?\"}, {\"user\": \"gpt\", \"message\": \"Ask Sage is...\"}]`\n\nWhen sending via form data, the message must be JSON-encoded.\n",
"example": "[{\"user\": \"me\", \"message\": \"Analyze this file\"}, {\"user\": \"gpt\", \"message\": \"I will analyze the file for you...\"}]"
},
"persona": {
"type": "string"
},
"tools": {
"type": "string"
},
"enabled_mcp_tools": {
"type": "string"
},
"tools_to_execute": {
"type": "string"
},
"tool_choice": {
"type": "string"
},
"reasoning_effort": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"mode": {
"type": "string"
},
"deep_agent_id": {
"type": "string"
},
"dataset": {
"type": "string"
},
"limit_references": {
"type": "string"
},
"temperature": {
"type": "string"
},
"model": {
"type": "string"
},
"live": {
"type": "string"
},
"streaming": {
"type": "string"
},
"usage": {
"type": "string"
},
"timezone": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful completion with file processing",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompletionResponse"
}
}
}
}
}
}
},
"/list-agents": {
"get": {
"summary": "List Agents",
"description": "Returns a list of all agents available to the authenticated user.",
"operationId": "list_agents_ep",
"responses": {
"200": {
"description": "A list of available agents.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"agent_mode": {
"type": "string",
"enum": [
"single",
"router",
"autonomous"
]
},
"primary_workflow_uuid": {
"type": "string",
"format": "uuid"
},
"current_version": {
"type": "integer"
},
"is_published": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"count": {
"type": "integer",
"description": "The total number of agents returned.",
"example": 1
},
"status": {
"type": "integer",
"description": "The HTTP status code.",
"example": 200
}
}
}
}
}
},
"401": {
"description": "Authentication failed."
},
"500": {
"description": "Internal Server Error."
}
}
},
"post": {
"summary": "List Agents (POST)",
"description": "Returns a list of all agents available to the authenticated user."
# --- truncated at 32 KB (141 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ask-sage/refs/heads/main/openapi/ask-sage-server-openapi.json