🖥️ Server API Documentation

Complete guide to Server endpoints for models, datasets, queries, and AI operations

📑 Table of contents

📖 Reference Documentation
API Endpoints

📚 Base URL: https://api.asksage.ai/server/

⚠️ Important: Make sure to use the correct Base URL associated with your tenant.

🔑 Authentication: Use either a Static API key or a 24-hour access token in the x-access-tokens header.

📖 Reference Documentation

For detailed API specifications, visit the Ask Sage Server API Swagger Documentation

API Endpoints

Get Models

POST https://api.asksage.ai/server/get-models

Retrieve a list of all available AI models for your tenant.

📝 Note: Available models vary based on your tenant configuration.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response (object) - Contains:

object - Type of object returned (e.g., 'list')
data - Array of model objects with:
- created - Model creation date
- id - Unique model identifier
- name - Model name
- owned_by - Model owner

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-models' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json'import requests

url = 'https://api.asksage.ai/server/get-models'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-models', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Get Personas

POST https://api.asksage.ai/server/get-personas

Retrieve all available personas, including custom personas created in the platform.

💡 Tip: When using personas with the /query endpoint, reference them by their ID number (e.g., Ask Sage persona = ID 1).

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response (array) - Array of persona objects containing:

id - Unique persona identifier
name - Persona name
description - Persona purpose and capabilities
prompt - System prompt that guides responses
date_creation - Creation timestamp
date_modification - Last modified timestamp
public - Public accessibility flag

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-personas' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json'import requests

url = 'https://api.asksage.ai/server/get-personas'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-personas', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Get Datasets

POST https://api.asksage.ai/server/get-datasets

Retrieve all available datasets, including custom datasets created in the platform.

📝 Note: Dataset names follow the format: user_custom_USERID_DATASETNAME_content

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response (array) - List of available dataset names

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-datasets' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json'import requests

url = 'https://api.asksage.ai/server/get-datasets'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-datasets', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Get Plugins

POST https://api.asksage.ai/server/get-plugins

Retrieve all available plugins/agents that can be utilized via the API.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response (array) - Array of plugin objects containing:

category - Plugin category (e.g., 'Acquisition', 'Audio')
description - Plugin functionality description
fields - Array of required/optional fields
id - Unique plugin identifier
paid_only - Paid user restriction flag
plugin_name - Plugin name
prompt_template - Associated prompt template
title - Plugin display title

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-plugins' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json'import requests

url = 'https://api.asksage.ai/server/get-plugins'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-plugins', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Tokenizer

POST https://api.asksage.ai/server/tokenizer

Calculate the number of tokens in your content for a specific model.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

content string Required

The text content to tokenize.

model string Required

The model to use for tokenization (e.g., "gpt-4o-mini").

📤 Response Details

200 Success

response (string) - Token count as a string

400 Error

Invalid request or missing parameters

curl -X POST 'https://api.asksage.ai/server/tokenizer' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Your text content here",
    "model": "gpt-4o-mini"
  }'import requests

url = 'https://api.asksage.ai/server/tokenizer'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'content': 'Your text content here',
    'model': 'gpt-4o-mini'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/tokenizer', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Your text content here',
    model: 'gpt-4o-mini'
  })
});

const data = await response.json();
console.log(data);

File Upload

POST https://api.asksage.ai/server/file

Upload and convert files to text/plain format for processing.

📏 File Size Limits: Max 250MB for documents, 500MB for audio/video files

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

file file Required

The file to upload and process.

📤 Response Details

200 Success

response - "OK" status message

ret - Extracted text content

status - HTTP status code (200)

400 Error

Invalid file or upload failure

curl -X POST 'https://api.asksage.ai/server/file' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file.pdf'import requests

url = 'https://api.asksage.ai/server/file'
headers = {
    'x-access-tokens': 'your_access_token'
}
files = {
    'file': open('/path/to/file.pdf', 'rb')
}

response = requests.post(url, headers=headers, files=files)
print(response.json())import FormData from 'form-data';
import fs from 'fs';

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/file.pdf'));

const response = await fetch('https://api.asksage.ai/server/file', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log(data);

Train

POST https://api.asksage.ai/server/train

Add content to your knowledge base with optional summarization.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

context string Required

Short context/metadata about the content.

content string Required

The actual content to train on.

summarize boolean Optional

Whether to summarize the content before training.

summarize_model string Optional

Model to use for summarization (e.g., "gpt-4o-mini").

force_dataset string Optional

Force content into a specific dataset.

📤 Response Details

200 Success

response - Training result message

embedding - Vector embedding ID

status - HTTP status code

400 Error

Invalid request or missing required fields

curl -X POST 'https://api.asksage.ai/server/train' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "context": "Product documentation",
    "content": "Your content here...",
    "summarize": true,
    "summarize_model": "gpt-4o-mini",
    "force_dataset": "user_custom_123_MyDataset_content"
  }'import requests

url = 'https://api.asksage.ai/server/train'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'context': 'Product documentation',
    'content': 'Your content here...',
    'summarize': True,
    'summarize_model': 'gpt-4o-mini',
    'force_dataset': 'user_custom_123_MyDataset_content'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/train', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    context: 'Product documentation',
    content: 'Your content here...',
    summarize: true,
    summarize_model: 'gpt-4o-mini',
    force_dataset: 'user_custom_123_MyDataset_content'
  })
});

const data = await response.json();
console.log(data);

Query

POST https://api.asksage.ai/server/query

Main endpoint for generating AI completions based on your input with full customization options.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

message string | array Required

Your query message. Can be a string or conversation array: [{user: "me", message: "Hello"}]

persona integer Optional

Persona ID to use (default: 1). Get IDs from /get-personas.

dataset string | array Optional

Dataset(s) to query. Use "all", "none", or specific dataset names.

model string Optional

AI model to use (default: "openai_gpt"). Options: gpt-4o-mini, claude2, etc.

temperature number Optional

Response randomness (0.0-1.0, default: 0.0). Higher = more creative.

limit_references integer Optional

Max number of knowledge base references. 0 = no embeddings.

live integer Optional

Web search mode: 0 = off, 1 = Google results, 2 = Google + web crawl.

system_prompt string Optional

Custom system prompt (overrides default - use with caution).

tools array Optional

Format depends on the Model being used.

usage boolean Optional

Include usage statistics in the response. Set usage to true to enable. Default is false.

📤 Response Details

200 Success

response - Status message

message - AI-generated response

uuid - Unique response identifier

references - Knowledge base sources used

embedding_down - Embedding service status

vectors_down - Vector database status

400 Error

Invalid request or missing required fields

curl -X POST 'https://api.asksage.ai/server/query' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "What is Ask Sage?",
    "persona": 1,
    "dataset": ["dataset1", "dataset2"],
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "limit_references": 5,
    "live": 1
  }'import requests

url = 'https://api.asksage.ai/server/query'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'message': 'What is Ask Sage?',
    'persona': 1,
    'dataset': ['dataset1', 'dataset2'],
    'model': 'gpt-4o-mini',
    'temperature': 0.7,
    'limit_references': 5,
    'live': 1
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/query', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What is Ask Sage?',
    persona: 1,
    dataset: ['dataset1', 'dataset2'],
    model: 'gpt-4o-mini',
    temperature: 0.7,
    limit_references: 5,
    live: 1
  })
});

const data = await response.json();
console.log(data);

Query With File

POST https://api.asksage.ai/server/query_with_file

Query the AI with file attachments for context-aware responses.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

message string Required

Your query about the file(s).

file string | array Required

File path(s) to include. Can be a single file or array of files.

💡 Tip: All optional parameters from the /query endpoint are also available here.

📤 Response Details

200 Success

Same response structure as /query endpoint

400 Error

Invalid request, missing file, or file processing error

curl -X POST 'https://api.asksage.ai/server/query_with_file' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "file": "document.pdf",
    "message": "Summarize this document",
    "model": "gpt-4o-mini"
  }'import requests

url = 'https://api.asksage.ai/server/query_with_file'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'file': 'document.pdf',
    'message': 'Summarize this document',
    'model': 'gpt-4o-mini'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/query_with_file', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file: 'document.pdf',
    message: 'Summarize this document',
    model: 'gpt-4o-mini'
  })
});

const data = await response.json();
console.log(data);

Follow-Up Questions

POST https://api.asksage.ai/server/follow-up-questions

Generate contextual follow-up questions based on conversation history.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

message array Required

Conversation history: [{user: "me", message: "..."}]

model string Optional

Model to use for generating questions.

dataset string Optional

Dataset context for questions (use "none" to disable).

📤 Response Details

200 Success

message - Array of suggested follow-up questions

status - HTTP status code

400 Error

Invalid request or missing conversation history

curl -X POST 'https://api.asksage.ai/server/follow-up-questions' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": [
      {"user": "me", "message": "What is Ask Sage?"}
    ],
    "model": "gpt-4o-mini",
    "dataset": "none"
  }'import requests

url = 'https://api.asksage.ai/server/follow-up-questions'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'message': [
        {'user': 'me', 'message': 'What is Ask Sage?'}
    ],
    'model': 'gpt-4o-mini',
    'dataset': 'none'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/follow-up-questions', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: [
      {user: 'me', message: 'What is Ask Sage?'}
    ],
    model: 'gpt-4o-mini',
    dataset: 'none'
  })
});

const data = await response.json();
console.log(data);

List MCP Servers (GET)

GET https://api.asksage.ai/server/list-mcp-servers

Retrieve all configured MCP (Model Context Protocol) servers.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

include_inactive boolean (query) Optional

Include inactive servers in results (default: false).

📤 Response Details

200 Success

count - Number of MCP servers

response - Array of server objects with:

id - Server ID
created_at - Creation timestamp
description - Server description
metadata_json - Detailed server metadata

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/list-mcp-servers?include_inactive=false' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/list-mcp-servers'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}
params = {'include_inactive': False}

response = requests.get(url, headers=headers, params=params)
print(response.json())const response = await fetch('https://api.asksage.ai/server/list-mcp-servers?include_inactive=false', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

List MCP Servers (POST)

POST https://api.asksage.ai/server/list-mcp-servers

Retrieve all configured MCP servers using POST method.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

include_inactive boolean Optional

Include inactive servers in results.

📤 Response Details

200 Success

Same response structure as GET method

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/list-mcp-servers' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"include_inactive": false}'import requests

url = 'https://api.asksage.ai/server/list-mcp-servers'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {'include_inactive': False}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/list-mcp-servers', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ include_inactive: false })
});

const data = await response.json();
console.log(data);

List MCP Whitelisted Servers

GET https://api.asksage.ai/server/list-mcp-whitelisted-servers

Get a list of all whitelisted MCP servers available for use.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - List of whitelisted server names

status - HTTP status code

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/list-mcp-whitelisted-servers' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/list-mcp-whitelisted-servers'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/list-mcp-whitelisted-servers', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

List MCP Tools

GET https://api.asksage.ai/server/list-mcp-tools

Retrieve all available MCP tools from configured servers.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

count - Number of available tools

response - Array of tool objects

server - Server details for each tool

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/list-mcp-tools' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/list-mcp-tools'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/list-mcp-tools', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Get All Files Ingested

GET https://api.asksage.ai/server/get-all-files-ingested

Retrieve a complete list of all files that have been ingested into the system.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - Status message

files - Array of ingested file details

status - HTTP status code

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/get-all-files-ingested' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/get-all-files-ingested'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-all-files-ingested', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Execute Plugin

POST https://api.asksage.ai/server/execute-plugin

Execute a specific plugin with provided values.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

plugin_name string Required

Name of the plugin to execute.

plugin_values string Required

Plugin values as JSON string.

model string Optional

Model to use for plugin execution.

live integer Optional

Live mode setting.

📤 Response Details

200 Success

Plugin execution result (streaming)

Media type: text/plain

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/execute-plugin' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: multipart/form-data' \
  -F 'plugin_name=your_plugin_name' \
  -F 'plugin_values={"key": "value"}' \
  -F 'model=gpt-4o-mini' \
  -F 'live=1'import requests

url = 'https://api.asksage.ai/server/execute-plugin'
headers = {
    'x-access-tokens': 'your_access_token'
}
data = {
    'plugin_name': 'your_plugin_name',
    'plugin_values': '{"key": "value"}',
    'model': 'gpt-4o-mini',
    'live': 1
}

response = requests.post(url, headers=headers, data=data)
print(response.text)const formData = new FormData();
formData.append('plugin_name', 'your_plugin_name');
formData.append('plugin_values', JSON.stringify({ key: 'value' }));
formData.append('model', 'gpt-4o-mini');
formData.append('live', '1');

const response = await fetch('https://api.asksage.ai/server/execute-plugin', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token'
  },
  body: formData
});

const data = await response.text();
console.log(data);

Execute Plugin with File

POST https://api.asksage.ai/server/execute-plugin-with-file

Execute a plugin that requires file input.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

file string($binary) Required

File to process with the plugin.

plugin_name string Required

Name of the plugin to execute.

plugin_values string Optional

Plugin values as JSON string (optional).

model string Optional

Model to use.

live integer Optional

Live mode setting.

📤 Response Details

200 Success

response - Plugin execution response

message - Status message

embedding_down - Embedding status (boolean)

vectors_down - Vectors status (boolean)

uuid - Unique identifier

references - Reference information

type - Response type

added_obj - Additional objects

usage - Usage statistics

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/execute-plugin-with-file' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/file.pdf' \
  -F 'plugin_name=your_plugin_name' \
  -F 'plugin_values={"key": "value"}' \
  -F 'model=gpt-4o-mini' \
  -F 'live=1'import requests

url = 'https://api.asksage.ai/server/execute-plugin-with-file'
headers = {
    'x-access-tokens': 'your_access_token'
}
files = {
    'file': ('filename.pdf', open('/path/to/your/file.pdf', 'rb'), 'application/pdf')
}
data = {
    'plugin_name': 'your_plugin_name',
    'plugin_values': '{"key": "value"}',
    'model': 'gpt-4o-mini',
    'live': 1
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())const formData = new FormData();
formData.append('file', fileInput.files[0]); // File from input element
formData.append('plugin_name', 'your_plugin_name');
formData.append('plugin_values', JSON.stringify({ key: 'value' }));
formData.append('model', 'gpt-4o-mini');
formData.append('live', '1');

const response = await fetch('https://api.asksage.ai/server/execute-plugin-with-file', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token'
  },
  body: formData
});

const data = await response.json();
console.log(data);

Get Deep Agent

POST https://api.asksage.ai/server/get-deep-agent

Get streaming updates from a deep agent.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

deep_agent_id integer Required

The ID of the deep agent to retrieve updates from.

📤 Response Details

200 Success

Deep agent updates (streaming)

Media type: text/plain

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-deep-agent' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "deep_agent_id": 0
  }'import requests

url = 'https://api.asksage.ai/server/get-deep-agent'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'deep_agent_id': 0
}

response = requests.post(url, headers=headers, json=data)
print(response.text)const response = await fetch('https://api.asksage.ai/server/get-deep-agent', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deep_agent_id: 0
  })
});

const data = await response.text();
console.log(data);

Add MCP Server

POST https://api.asksage.ai/server/add-mcp-server

Add a new MCP (Model Context Protocol) server for the user.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

server_name string Required

Name of the MCP server.

server_url string Required

URL of the MCP server.

server_type string Required

Type of the MCP server.

description string Required

Description of the MCP server.

metadata_json string Required

Metadata for the MCP server as a JSON string.

📤 Response Details

200 Success

response - Status message

server_id - ID of the newly created MCP server

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/add-mcp-server' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "server_name": "My MCP Server",
    "server_url": "https://your-mcp-server.com",
    "server_type": "API",
    "description": "Description of the MCP server",
    "metadata_json": "{\"key\": \"value\"}"
  }'import requests

url = 'https://api.asksage.ai/server/add-mcp-server'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'server_name': 'My MCP Server',
    'server_url': 'https://your-mcp-server.com',
    'server_type': 'API',
    'description': 'Description of the MCP server',
    'metadata_json': '{"key": "value"}'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/add-mcp-server', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server_name: 'My MCP Server',
    server_url: 'https://your-mcp-server.com',
    server_type: 'API',
    description: 'Description of the MCP server',
    metadata_json: '{"key": "value"}'
  })
});

const data = await response.json();
console.log(data);

Update MCP Server

PUT https://api.asksage.ai/server/update-mcp-server

Update an existing MCP server configuration.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

server_id integer Required

ID of the MCP server to update.

server_name string Optional

Updated name of the MCP server.

server_url string Optional

Updated URL of the MCP server.

server_type string Optional

Updated type of the MCP server.

description string Optional

Updated description of the MCP server.

metadata_json string Optional

Updated metadata for the MCP server as a JSON string.

📤 Response Details

200 Success

response - Status message

server_id - ID of the updated MCP server

status - Status code

400 Error

Invalid request or authentication failure

curl -X PUT 'https://api.asksage.ai/server/update-mcp-server' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "server_id": 0,
    "server_name": "Updated MCP Server",
    "server_url": "https://your-updated-mcp-server.com",
    "server_type": "API",
    "description": "Updated description of the MCP server",
    "metadata_json": "{\"key\": \"value\"}"
  }'import requests

url = 'https://api.asksage.ai/server/update-mcp-server'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'server_id': 0,
    'server_name': 'Updated MCP Server',
    'server_url': 'https://your-updated-mcp-server.com',
    'server_type': 'API',
    'description': 'Updated description of the MCP server',
    'metadata_json': '{"key": "value"}'
}

response = requests.put(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/update-mcp-server', {
  method: 'PUT',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server_id: 0,
    server_name: 'Updated MCP Server',
    server_url: 'https://your-updated-mcp-server.com',
    server_type: 'API',
    description: 'Updated description of the MCP server',
    metadata_json: '{"key": "value"}'
  })
});

const data = await response.json();
console.log(data);

Delete MCP Server

DELETE https://api.asksage.ai/server/delete-mcp-server

Soft delete an MCP server by setting it as inactive.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

server_id integer Required

ID of the MCP server to delete.

📤 Response Details

200 Success

response - Status message

server_id - ID of the deleted MCP server

status - Status code

404 Error

Server not found or access denied

curl -X DELETE 'https://api.asksage.ai/server/delete-mcp-server' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "server_id": 0
  }'import requests

url = 'https://api.asksage.ai/server/delete-mcp-server'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'server_id': 0
}

response = requests.delete(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/delete-mcp-server', {
  method: 'DELETE',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server_id: 0
  })
});

const data = await response.json();
console.log(data);

Delete Dataset

DELETE https://api.asksage.ai/server/dataset

Delete a specific dataset.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

dataset string Required

Name of the dataset to delete.

📤 Response Details

200 Success

response - Status message

status - Status code

400 Error

Invalid request or authentication failure

curl -X DELETE 'https://api.asksage.ai/server/dataset' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "dataset": "your_dataset_name"
  }'import requests

url = 'https://api.asksage.ai/server/dataset'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'dataset': 'your_dataset_name'
}

response = requests.delete(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/dataset', {
  method: 'DELETE',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dataset: 'your_dataset_name'
  })
});

const data = await response.json();
console.log(data);

Delete Filename from Dataset

POST https://api.asksage.ai/server/delete-filename-from-dataset

Remove a specific file from a dataset.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

dataset string Required

Name of the dataset containing the file.

filename string Required

Name of the file to delete from the dataset.

📤 Response Details

200 Success

response - Status message

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/delete-filename-from-dataset' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "dataset": "your_dataset_name",
    "filename": "your_filename.pdf"
  }'import requests

url = 'https://api.asksage.ai/server/delete-filename-from-dataset'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'dataset': 'your_dataset_name',
    'filename': 'your_filename.pdf'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/delete-filename-from-dataset', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dataset: 'your_dataset_name',
    filename: 'your_filename.pdf'
  })
});

const data = await response.json();
console.log(data);

Copy Files to Dataset

POST https://api.asksage.ai/server/copy-files-dataset

Copy files from one dataset to another.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

dataset string Required

Name of the destination dataset to copy files to.

files array Required

Array of file objects to copy. Each object contains filename and source_string properties.

📤 Response Details

200 Success

response - Array of status messages for copied files

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/copy-files-dataset' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "dataset": "destination_dataset_name",
    "files": [
      {
        "filename": "file1.pdf",
        "source_string": "source_dataset_name"
      },
      {
        "filename": "file2.pdf",
        "source_string": "source_dataset_name"
      }
    ]
  }'import requests

url = 'https://api.asksage.ai/server/copy-files-dataset'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'dataset': 'destination_dataset_name',
    'files': [
        {
            'filename': 'file1.pdf',
            'source_string': 'source_dataset_name'
        },
        {
            'filename': 'file2.pdf',
            'source_string': 'source_dataset_name'
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/copy-files-dataset', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dataset: 'destination_dataset_name',
    files: [
      {
        filename: 'file1.pdf',
        source_string: 'source_dataset_name'
      },
      {
        filename: 'file2.pdf',
        source_string: 'source_dataset_name'
      }
    ]
  })
});

const data = await response.json();
console.log(data);

Vote Down

POST https://api.asksage.ai/server/vote-down

Mark a response as unhelpful or incorrect.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

uuid string Required

Unique identifier of the response to vote down.

📤 Response Details

200 Success

response - Status message

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/vote-down' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuid": "your_response_uuid"
  }'import requests

url = 'https://api.asksage.ai/server/vote-down'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}
data = {
    'uuid': 'your_response_uuid'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/vote-down', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uuid: 'your_response_uuid'
  })
});

const data = await response.json();
console.log(data);

Count Monthly Tokens

GET https://api.asksage.ai/server/count-monthly-tokens

Returns the count of tokens used this month.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - Token count for the current month

status - Status code

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/count-monthly-tokens' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/count-monthly-tokens'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/count-monthly-tokens', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Count Monthly Tokens by App

POST https://api.asksage.ai/server/count-monthly-tokens

Returns the count of tokens used this month for a specific app.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - Token count for the current month

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/count-monthly-tokens' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json'import requests

url = 'https://api.asksage.ai/server/count-monthly-tokens'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/count-monthly-tokens', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Count Monthly Teaching Tokens

GET https://api.asksage.ai/server/count-monthly-teach-tokens

Returns the count of teaching/training tokens used this month.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - Teaching token count for the current month

status - Status code

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/count-monthly-teach-tokens' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/count-monthly-teach-tokens'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/count-monthly-teach-tokens', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Train with File

POST https://api.asksage.ai/server/train-with-file

Train the model using file content.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

file string($binary) Required

File to train from.

dataset string Optional

Dataset to add content to.

📤 Response Details

200 Success

response - Status message

embedding - Array of embedding strings

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/train-with-file' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/file.pdf' \
  -F 'dataset=your_dataset_name'import requests

url = 'https://api.asksage.ai/server/train-with-file'
headers = {
    'x-access-tokens': 'your_access_token'
}
files = {
    'file': ('filename.pdf', open('/path/to/your/file.pdf', 'rb'), 'application/pdf')
}
data = {
    'dataset': 'your_dataset_name'
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())const formData = new FormData();
formData.append('file', fileInput.files[0]); // File from input element
formData.append('dataset', 'your_dataset_name');

const response = await fetch('https://api.asksage.ai/server/train-with-file', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token'
  },
  body: formData
});

const data = await response.json();
console.log(data);

Train with Array

POST https://api.asksage.ai/server/train-with-array

Train the model using an array of content.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

data string Required

JSON array of data to train.

dataset string Required

Dataset name.

context string Optional

Additional context.

filename string Optional

Source filename.

📤 Response Details

200 Success

response - Status message

embedding - Array of embedding strings

status - Status code

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/train-with-array' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: multipart/form-data' \
  -F 'data=["content item 1", "content item 2", "content item 3"]' \
  -F 'dataset=your_dataset_name' \
  -F 'context=Additional context information' \
  -F 'filename=source_file.txt'import requests
import json

url = 'https://api.asksage.ai/server/train-with-array'
headers = {
    'x-access-tokens': 'your_access_token'
}
data = {
    'data': json.dumps(['content item 1', 'content item 2', 'content item 3']),
    'dataset': 'your_dataset_name',
    'context': 'Additional context information',
    'filename': 'source_file.txt'
}

response = requests.post(url, headers=headers, data=data)
print(response.json())const formData = new FormData();
formData.append('data', JSON.stringify(['content item 1', 'content item 2', 'content item 3']));
formData.append('dataset', 'your_dataset_name');
formData.append('context', 'Additional context information');
formData.append('filename', 'source_file.txt');

const response = await fetch('https://api.asksage.ai/server/train-with-array', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token'
  },
  body: formData
});

const data = await response.json();
console.log(data);

Get Secrets

GET https://api.asksage.ai/server/get-secrets

Returns a list of user's stored secrets (keys only, not values).

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

📤 Response Details

200 Success

response - Array of secret names (keys only)

status - Status code

400 Error

Invalid request or authentication failure

curl -X GET 'https://api.asksage.ai/server/get-secrets' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/get-secrets'
headers = {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/get-secrets', {
  method: 'GET',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Get Text to Speech

POST https://api.asksage.ai/server/get-text-to-speech

Generate audio from text using text-to-speech.

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

text string Required

The text to convert to speech.

voice string Required

The voice to use for speech generation. Options include: alloy, echo, fable, onyx, nova, shimmer.

model string Required

The model to use for text-to-speech. Options: tts (optimized for speed) or tts-hd (optimized for quality).

📤 Response Details

200 Success

Audio file - Returns audio/mpeg file containing the generated speech

400 Error

Invalid request or authentication failure

curl -X POST 'https://api.asksage.ai/server/get-text-to-speech' \
  -H 'x-access-tokens: your_access_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/mpeg' \
  -d '{
    "text": "Hello, this is a sample text to convert to speech.",
    "voice": "alloy",
    "model": "tts-hd"
  }' \
  --output speech.mp3import requests

url = 'https://api.asksage.ai/server/get-text-to-speech'
headers = {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json',
    'Accept': 'audio/mpeg'
}
data = {
    'text': 'Hello, this is a sample text to convert to speech.',
    'voice': 'alloy',
    'model': 'tts-hd'
}

response = requests.post(url, headers=headers, json=data)

# Save the audio file
with open('speech.mp3', 'wb') as f:
    f.write(response.content)const response = await fetch('https://api.asksage.ai/server/get-text-to-speech', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token',
    'Content-Type': 'application/json',
    'Accept': 'audio/mpeg'
  },
  body: JSON.stringify({
    text: 'Hello, this is a sample text to convert to speech.',
    voice: 'alloy',
    model: 'tts-hd'
  })
});

// Convert response to blob and download
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'speech.mp3';
a.click();