Server Parameters and Responses

In this section will cover each endpoint in the Ask Sage API, including the parameters and responses for each endpoint.

Table of contents

1. Server API Endpoints:
   1. Get Models
   2. Get Personas
   3. Get Datasets
   4. Get Plugins
   5. Tokenizer
   6. File
   7. Train
   8. Query
   9. Query With File
   10. Follow Up Questions

Server API Endpoints:

The Server API is used for managing the server, including the Ask Sage API. We have the following Swagger documentation for the Server API:

• The Base URL for the Server API is: [ Base URL: api.asksage.ai/server/ ]

Make sure to use the correct Base URL associated with your tenant.

Users can use the Static API key Generated in the Ask Sage Platform as the required token for authentication. However, there is no expiration on the API key, while if you generate a token it is valid for 24 hours.
"x-access-tokens": "your_access_token_here"
"x-access-tokens": "api-key"

The following table shows the available endpoints in the Server API:

Endpoint	Description
/get-models	Returns a list of available models via the Ask Sage services
/query	Main endpoint for generating completions based on the user’s input
/query_with_file	Query with file endpoint for generating completions based on the user’s input
/follow_up_questions	Endpoint for generating follow-up questions based on the user’s input
/tokenizer	Endpoint for getting tokens of string value
/get-personas	Endpoint for getting the tokens of string
/get-datasets	Returns a list of available datasets
/get-plugins	Returns a list of available plugins
/train	Trains the model based on the user’s input
/file	Converts a supported file to plain/text

---

Get Models

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

Provides the list of models available via the Ask Sage API.

Models available vary based on respective tenant.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

Returns

On success (HTTP 200):

response object Contains the following properties:

- object string

The type of object returned (e.g., 'list').

- data array

Contains objects with the following fields:

- created string

The creation date of the model.

- id string

The unique identifier for the model.

- name string

The name of the model.

- object string

The type of object (e.g., 'model').

- owned_by string

The owner of the model.

- response array

A list of model names available.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The status code of the response.

Bash Python JavaScript

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

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

response = requests.post(url, headers=headers)
print(response.json())
        
         import fetch from 'node-fetch';
        fetch('https://api.asksage.ai/server/get-models', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Get Personas

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

Provides the list of personas available via the Ask Sage API.

Custome created personas created in the platform may also be leverged via the API.

When selecting a persona to be used with the /query endpoint use the persona ID to reference the persona you are interested in using. For example Ask Sage persona is ID = 1, set persona equal to 1

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

Returns

On success (HTTP 200):

response array Contains objects with:

- id integer

The unique identifier for the persona.

- name string

The name of the persona.

- description string

A brief description of the persona's purpose and capabilities.

- prompt string

The specific prompt that guides the persona's responses.

- date_creation string

The date and time when the persona was created.

- date_modification string

The date and time when the persona was last modified.

- public boolean

Indicates whether the persona is publicly accessible.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The status code of the response.

Bash Python JavaScript

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

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

response = requests.post(url, headers=headers)
print(response.json())
        
        import fetch from 'node-fetch';
        fetch('https://api.asksage.ai/server/get-personas', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Get Datasets

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

Takes the user’s token as input and returns the list of available datasets.

Custome created datasets created in the platform may also be leverged via the API.

When selecting a dataset to be used with the /query endpoint use the name displayed by the endpoint. For example the dataset name will be displayed as follows user_custom_USERID_DATASETNAME_content, where USERID and DATASETNAME is unique per customer.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

Returns

On success (HTTP 200):

response array Contains a list of datasets:

- response array

A list of dataset names available to the user.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The status code of the response.

Bash Python JavaScript

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

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

response = requests.post(url, headers=headers)
print(response.json())
        
         import fetch from 'node-fetch';
        fetch('https://api.asksage.ai/server/get-datasets', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Get Plugins

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

Takes the user’s token as input and returns the list of available plugins/agents.

Plugins/Agents on Ask Sage can be utilized via the API.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

Returns

On success (HTTP 200):

response array Contains objects with:

- category string

The category of the plugin (e.g., 'Acquisition', 'Audio', etc.).

- description string

A brief description of what the plugin does.

- fields array

Contains objects with the following fields:

- name string

The name of the field required by the plugin.

- description string

A description of the field's purpose.

- type string

The data type of the field (e.g., 'textarea', 'file', 'text').

- required boolean

Indicates whether the field is required.

- id string

The unique identifier for the plugin.

- paid_only boolean

Indicates if the plugin is only available for paid users.

- plugin_name string

The name of the plugin.

- prompt_template string

The template used for prompts associated with the plugin.

- regex string

The regular expression pattern for validating the prompt.

- title string

The title of the plugin.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The status code of the response.

Bash Python JavaScript

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

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

response = requests.post(url, headers=headers)
print(response.json())
        
        import fetch from 'node-fetch';
        fetch('https://api.asksage.ai/server/get-plugins', {
  method: 'POST',
  headers: {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Tokenizer

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

Takes the user’s token and content as input and returns the number of tokens.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

data object Required

JSON object containing:

• content: string - The content to be processed.
• model: string - The model to be used (e.g., "gpt-4o-mini").

---

Returns

On success (HTTP 200):

response string

The response message indicating the token count (e.g., "18").

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The status code of the response.

Bash Python JavaScript

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

url = "https://api.asksage.ai/server/tokenizer"
headers = {
    "x-access-tokens": "your_access_token_here",
    "Content-Type": "application/json"
}
data = {
    "content": "Content entered",
    "model": "gpt-4o-mini"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
        
        import fetch from 'node-fetch';

const url = 'https://api.asksage.ai/server/tokenizer';
const headers = {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
};
const data = {
    content: 'Content entered',
    model: 'gpt-4o-mini'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data) // Include the data payload
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

File

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

File ingest and text/plain conversion

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

file file Required

File to ingest (max 250MB for non-audio/video files, 500MB for audio/video files).

---

Returns

On success (HTTP 200):

response string

Returns 'OK' indicating the request was successful.

ret string

Text/plain response content.

status integer

The HTTP status code (200).

---

On error (HTTP 400):

response string

An error message describing the issue.

status integer

The HTTP status code (400).

Bash Python JavaScript

        
curl -X POST https://api.asksage.ai/server/file \
-H "x-access-tokens: your_access_token_here" \
-H 'Content-Type: multipart/form-data' \
-F 'file=@/path/to/your/file'
        
        import requests
url = "https://api.asksage.ai/server/file"
headers = {
    "x-access-tokens": "your_access_token_here"
}
files = {
    'file': open('/path/to/your/file', 'rb')  # Open the file in binary mode
}

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

const url = 'https://api.asksage.ai/server/file';
const headers = {
    'x-access-tokens': 'your_access_token_here',
};

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/your/file')); // Replace with your file path
fetch(url, {
    method: 'POST',
    headers: {
        ...headers,
        ...form.getHeaders() // Include the headers for multipart/form-data
    },
    body: form // Include the form data
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Train

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

Takes the user’s token, content, and other optional parameters as input and returns the training result

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

content object Required

JSON object containing:

• context: string - Short context (metadata) about the content.
• content: string - User's input content.
• summarize: boolean
  Optional
  - Summarize the content.
• summarize_model: string
  Optional
  - Model to use for summarization.
• force_dataset: string
  Optional
  - Force a specific dataset.

---

Returns

On success (HTTP 200):

response object Contains the following properties:

- response string

The training result.

- embedding string

The vector embedding.

- status integer

The HTTP status code.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The HTTP status code.

Bash Python JavaScript

        
curl -X POST https://api.asksage.ai/server/train \
-H "x-access-tokens: your_access_token_here" \
-H "Content-Type: application/json" \
-d "{ \"context\": \"Short context about the content\", \"content\": \"User's input content\", \"summarize\": true,  \"summarize_model\": \"gpt-4o-mini\", \"force_dataset\": \"user_custom_USERID_DATASETNAME_content\" }"
        
        import requests
import json
url = "https://api.asksage.ai/server/train"
headers = {
    "x-access-tokens": "your_access_token_here",
    "Content-Type": "application/json"
}
data = {
    "context": "Short context about the content",
    "content": "User's input content",
    "summarize": True, 
    "summarize_model": "gpt-4o-mini",
    "force_dataset": "user_custom_USERID_DATASETNAME_content"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
        
        import fetch from 'node-fetch';
const url = 'https://api.asksage.ai/server/train';
const headers = {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
};

const data = {
    context: 'Short context about the content',
    content: "User's input content",
    summarize: true,
    summarize_model: 'gpt-4o-mini',
    force_dataset: 'user_custom_USERID_DATASETNAME_content'
};
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data) // Include the data payload
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error))
        
      

---

Query

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

Main endpoint for generating completions based on the user’s input

Takes the user’s token and content as input and returns the generated response.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

content object Required

JSON object containing:

• message: string - The message to be processed by the service. This can be a single message or an array of messages following this JSON format: [{ user: "me", message: "Who is Nic Chaillan?"}, { user: "gpt", message: "Nic Chaillan is..." }] .
• persona: string
  Optional
  - The persona to be used for the response. Default is 'default'. Get the list of available personas using get_personas. When assigning a persona use the persona ID not the name of it.
• system_prompt: string
  Optional
  - Custom system prompt. Overrides the system prompt from Ask Sage (only use if you know what you are doing).
• dataset: string
  Optional
  - The dataset to be used for the response. Default is 'all'. Other options include 'none' or your custom dataset, which must follow the format: user_content_USERID_DATASET-NAME_content. Replace content with what is provided by the /get-datsets, USERID with your user ID and DATASET-NAME with the name of your dataset.
• limit_references: integer
  Optional
  - The maximum number of references (embeddings) to be used. Default is None, meaning all references will be used. Use 1 to limit to 1 reference or 0 to remove embeddings. You can also set dataset to 'none'.
• temperature: number
  Optional
  - The temperature for the response generation. Default is 0.0. Higher values (up to 1.0) make the output more random.
• live: integer
  Optional
  - Live mode. Default is 0. Set to 1 to pull 10 results from Bing, or 2 to also summarize the top 2 web pages using our Web crawler.
• model: string
  Optional
  - The model to be used for response generation. Default is 'openai_gpt'. Other options include cohere, google-bison, gpt4, gpt4-32k, gpt35-16k, claude2, davinci, and llma2.
• tools: array
  Optional
  - Tools to be used in the request, following the OpenAI format.
• tool_choice: string
  Optional
  - Specifies the tool choice to be used in the request.

---

Returns

On success (HTTP 200):

response object Contains the following properties:

- response string

Response status.

- message string

Generated response message.

- embedding_down boolean

Embedding status.

- vectors_down boolean

Vectors status.

- uuid string

Unique identifier for the response.

- references string

References used in the response.

- teach boolean

Teaching status.

- status integer

The HTTP status code.

---

On error (HTTP 400):

- response string

Error message describing the issue.

- status integer

The HTTP status code.

Bash Python JavaScript

        
curl -X POST https://api.asksage.ai/server/query \
-H "x-access-tokens: your_access_token_here" \
-H "Content-Type: application/json" \
-d "{ \"message\": \"User's input message\", \"persona\": 1, \"system_prompt\": \"optional_custom_prompt\", \"dataset\": \"optional_dataset_name\", \"limit_references\": 0, \"temperature\": 0.7, \"live\": 1, \"model\": \"gpt-4o-mini\", \"tools\": \"optional_tools_value\", \"tool_choice\": \"optional_tool_choice_value\" }"
        
        import requests
import json

url = "https://api.asksage.ai/server/query"
headers = {
    "x-access-tokens": "your_access_token_here",
    "Content-Type": "application/json"
}
data = {
    "message": "User's input message",
    "persona": 1,
    "system_prompt": "optional_custom_prompt",
    "dataset": "optional_dataset_name",
    "limit_references": 0,
    "temperature": 0.7,
    "live": 1,
    "model": "gpt-4o-mini",
    "tools": "optional_tools_value",  # Add your tools value here
    "tool_choice": "optional_tool_choice_value"  # Add your tool choice value here
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
        
        import fetch from 'node-fetch';
const url = 'https://api.asksage.ai/server/query';
const headers = {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
};

const data = {
    message: "User's input message",
    persona: 1,
    system_prompt: "optional_custom_prompt",
    dataset: "optional_dataset_name",
    limit_references: 0,
    temperature: 0.7,
    live: 1,
    model: "gpt-4o-mini",
    tools: "optional_tools_value", // Add your tools value here
    tool_choice: "optional_tool_choice_value" // Add your tool choice value here
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data) // Include the data payload
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Query With File

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

Query with file endpoint for generating completions based on the user’s input

Takes the user’s token and content as input and returns the generated response.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

content object Required

JSON object containing:

• message: string - The message to be processed by the service. This can be a single message or an array of messages following this JSON format: [{ user: "me", message: "Who is Nic Chaillan?"}, { user: "gpt", message: "Nic Chaillan is..." }] .
• file: string
  Required
  - The file path to the File to be processed.
• persona: string
  Optional
  - The persona to be used for the response. Default is 'default'. Get the list of available personas using get_personas. When assigning a persona use the persona ID not the name of it.
• system_prompt: string
  Optional
  - Custom system prompt. Overrides the system prompt from Ask Sage (only use if you know what you are doing).
• dataset: string
  Optional
  - The dataset to be used for the response. Default is 'all'. Other options include 'none' or your custom dataset, which must follow the format: user_content_USERID_DATASET-NAME_content. Replace content with what is provided by the /get-datasets, USERID with your user ID and DATASET-NAME with the name of your dataset.
• limit_references: integer
  Optional
  - The maximum number of references (embeddings) to be used. Default is None, meaning all references will be used. Use 1 to limit to 1 reference or 0 to remove embeddings. You can also set dataset to 'none'.
• temperature: number
  Optional
  - The temperature for the response generation. Default is 0.0. Higher values (up to 1.0) make the output more random.
• live: integer
  Optional
  - Live mode. Default is 0. Set to 1 to pull 10 results from Bing, or 2 to also summarize the top 2 web pages using our Web crawler.
• model: string
  Optional
  - The model to be used for response generation. Default is 'openai_gpt'. Other options include cohere, google-bison, gpt4, gpt4-32k, gpt35-16k, claude2, davinci, and llma2.
• tools: array
  Optional
  - Tools to be used in the request, following the OpenAI format.
• tool_choice: string
  Optional
  - Specifies the tool choice to be used in the request.

---

Returns

On success (HTTP 200):

response object Contains the following properties:

- response string

Response status.

- message string

Generated response message.

- embedding_down boolean

Embedding status.

- vectors_down boolean

Vectors status.

- uuid string

Unique identifier for the response.

- references string

References used in the response.

- teach boolean

Teaching status.

- status integer

The HTTP status code.

---

On error (HTTP 400):

- response string

Error message describing the issue.

- status integer

The HTTP status code.

Bash Python JavaScript

        
curl -X POST https://api.asksage.ai/server/query \
-H "x-access-tokens: your_access_token_here" \
-H "Content-Type: application/json" \
-d "{ \"file\": \"file_path\", \"message\": \"what is in this document\", \"persona\": 1, \"system_prompt\": \"optional_custom_prompt\", \"dataset\": \"optional_dataset_name\", \"limit_references\": 0, \"temperature\": 0.7, \"live\": 1, \"model\": \"gpt-4o-mini\", \"tools\": \"optional_tools_value\", \"tool_choice\": \"optional_tool_choice_value\" }"
        
        import requests
import json

url = "https://api.asksage.ai/server/query"
headers = {
    "x-access-tokens": "your_access_token_here",
    "Content-Type": "application/json"
}
data = {
    "file": "file_path",  # Path to the file to be processed
    "message": "what is in this document",
    "persona": 1,
    "system_prompt": "optional_custom_prompt",
    "dataset": "optional_dataset_name",
    "limit_references": 0,
    "temperature": 0.7,
    "live": 1,
    "model": "gpt-4o-mini",
    "tools": "optional_tools_value",  # Add your tools value here
    "tool_choice": "optional_tool_choice_value"  # Add your tool choice value here
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
        
        import fetch from 'node-fetch';
const url = 'https://api.asksage.ai/server/query';
const headers = {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
};

const data = {
    file: "file_path",  // Path to the file to be processed
    message: "User's input message",
    persona: 1,
    system_prompt: "optional_custom_prompt",
    dataset: "optional_dataset_name",
    limit_references: 0,
    temperature: 0.7,
    live: 1,
    model: "gpt-4o-mini",
    tools: "optional_tools_value", // Add your tools value here
    tool_choice: "optional_tool_choice_value" // Add your tool choice value here
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data) // Include the data payload
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---

Follow Up Questions

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

Endpoint for generating follow-up questions based on the user’s input

Takes the user’s token and content as input and returns the generated response.

Request body

---

x-access-tokens string Required

The 24-hour Token or API Key used for authentication.

---

content object Required

JSON object containing:

• message: string - User's input message.

---

Returns

On success (HTTP 200):

response object Contains the following properties:

- response string

Response status.

- message string

Generated response message.

- embedding_down boolean

Embedding status.

- vectors_down boolean

Vectors status.

- uuid string

Unique identifier for the response.

- references string

References used in the response.

- teach boolean

Teaching status.

- status integer

The HTTP status code.

---

On error (HTTP 400):

- response string

An error message describing the issue.

- status integer

The HTTP status code.

Bash Python JavaScript

        
curl -X POST https://api.asksage.ai/server/follow-up-questions \
-H "x-access-tokens: your_access_token_here" \
-H 'Content-Type: application/json' \
-d '{"content": {"message": "User\'s input message"}}'
        
        import requests
import json

url = "https://api.asksage.ai/server/follow-up-questions"
headers = {
    "x-access-tokens": "your_access_token_here",
    "Content-Type": "application/json"
}
data = {
    "content": {
        "message": "User's input message"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
        
        import fetch from 'node-fetch';

const url = 'https://api.asksage.ai/server/follow-up-questions';
const headers = {
    'x-access-tokens': 'your_access_token_here',
    'Content-Type': 'application/json'
};
const data = {
    content: {
        message: "User's input message"
    }
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data) // Include the data payload
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
        
      

---