OpenAPI Specification
openapi: 3.0.3
info:
title: Ask Sage Server Admin Completions 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: Completions
description: Text generation and completions
paths:
/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:
- 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..."}]`
When sending via form data, the message must be JSON-encoded.
'
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.
Maximum file size: 500MB per file. Maximum number of files determined by server configuration.
'
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:
- 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..."}]`
When sending via form data, the message must be JSON-encoded.
'
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'
/follow-up-questions:
post:
summary: Generate follow-up questions
description: Generate relevant follow-up questions based on the conversation
tags:
- Completions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
$ref: '#/components/schemas/Message'
dataset:
type: string
default: all
model:
type: string
description: Model to use
responses:
'200':
description: Generated follow-up questions
content:
application/json:
schema:
$ref: '#/components/schemas/CompletionResponse'
get:
summary: Generate follow-up questions (GET)
description: Generate relevant follow-up questions based on the conversation
tags:
- Completions
responses:
'200':
description: Generated follow-up questions
content:
application/json:
schema:
$ref: '#/components/schemas/CompletionResponse'
components:
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...
ToolChoice:
oneOf:
- type: string
enum:
- auto
- none
- required
- type: object
properties:
type:
type: string
enum:
- function
function:
type: object
properties:
name:
type: string
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
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
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.