OpenAI Compatibility Guide

Seamlessly integrate Ask Sage using the standard OpenAI API format

Table of contents

1. What’s New?
2. Two Ways to Use OpenAI Format
3. New OpenAI-Compatible Endpoints
   1. Chat Completions
   2. List Available Models
4. Enhanced Ask Sage Endpoints
   1. Using OpenAI Format with /query
5. How It Works
6. Migration Guide
   1. Quick Comparison
   2. Key Benefits

What’s New?

Ask Sage now supports the OpenAI message format, making it incredibly easy to:

Easy Migration

Switch from OpenAI to Ask Sage with minimal code changes

Standard Format

Use the same API format and patterns as OpenAI

Familiar Interface

Leverage the standard OpenAI API format you already know

---

Two Ways to Use OpenAI Format

Option 1: New OpenAI-Compatible Endpoints

Pure OpenAI Standard
Use the /v1/* endpoints that follow the exact OpenAI API specification

• Drop-in replacement for OpenAI's API
• Standard Bearer token authentication
• Compatible with OpenAI client libraries
• Endpoints: /v1/chat/completions, /v1/models

Option 2: Enhanced Ask Sage Endpoints

Flexible Integration
Use existing /query endpoint with OpenAI format support

• Accepts both OpenAI and Ask Sage formats
• Uses x-access-tokens authentication
• Supports Ask Sage-specific parameters (persona, dataset, live search, etc.)
• 100% backward compatible with existing code

---

New OpenAI-Compatible Endpoints

Chat Completions

POST https://api.asksage.ai/server/v1/chat/completions

The main endpoint for conversational AI using the standard OpenAI format.

Authentication: Use Bearer token in the Authorization header

Request Parameters

Authorization string (header) Required

Bearer token authentication: Bearer YOUR_API_KEY

model string Required

The AI model to use (e.g., "gpt-4o-mini", "claude-35-sonnet", etc.)

messages array Required

Array of message objects with roles: system, user, or assistant

• role: Message role (system, user, assistant)
• content: Message content text

temperature number Optional

Controls randomness (0.0-2.0). Higher values make output more creative. Default: 1.0

max_tokens integer Optional

Maximum number of tokens to generate in the response

top_p number Optional

Nucleus sampling parameter (0.0-1.0). Default: 1.0

frequency_penalty number Optional

Reduces likelihood of repeating tokens (-2.0 to 2.0). Default: 0.0

presence_penalty number Optional

Increases likelihood of new topics (-2.0 to 2.0). Default: 0.0

tools array Optional

Array of tool/function definitions for function calling

tool_choice string Optional

Controls tool usage: "none", "auto", or specific tool. Default: "auto"

Response Details

200 Success

Response Structure:

• id: Unique completion ID
• object: "chat.completion"
• created: Unix timestamp
• model: Model used
• choices: Array containing:
  • index: Choice index
  • message: Response message object with role and content
  • finish_reason: Reason for completion (stop, length, etc.)
• usage: Token usage statistics

400 Error

Invalid request format or missing required parameters

401 Error

Authentication failure - invalid or missing API key

Example: Basic Chat Completion

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is Ask Sage?"}
    ]
  }'import requests

url = 'https://api.asksage.ai/server/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': 'What is Ask Sage?'}
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'What is Ask Sage?'}
    ]
  })
});

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

Example: Multi-Turn Conversation

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "My name is Alice."},
      {"role": "assistant", "content": "Nice to meet you, Alice!"},
      {"role": "user", "content": "What'\''s my name?"}
    ],
    "temperature": 0.3
  }'import requests

url = 'https://api.asksage.ai/server/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': 'My name is Alice.'},
        {'role': 'assistant', 'content': 'Nice to meet you, Alice!'},
        {'role': 'user', 'content': "What's my name?"}
    ],
    'temperature': 0.3
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'My name is Alice.'},
      {role: 'assistant', content: 'Nice to meet you, Alice!'},
      {role: 'user', content: "What's my name?"}
    ],
    temperature: 0.3
  })
});

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

Example: Function Calling

Tip: Function calling enables the model to call external functions or tools to retrieve information

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What'\''s the weather like in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather in a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'import requests

url = 'https://api.asksage.ai/server/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'user', 'content': "What's the weather like in San Francisco?"}
    ],
    'tools': [
        {
            'type': 'function',
            'function': {
                'name': 'get_weather',
                'description': 'Get the current weather in a location',
                'parameters': {
                    'type': 'object',
                    'properties': {
                        'location': {
                            'type': 'string',
                            'description': 'The city and state, e.g. San Francisco, CA'
                        },
                        'unit': {
                            'type': 'string',
                            'enum': ['celsius', 'fahrenheit']
                        }
                    },
                    'required': ['location']
                }
            }
        }
    ],
    'tool_choice': 'auto'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())const response = await fetch('https://api.asksage.ai/server/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'user', content: "What's the weather like in San Francisco?"}
    ],
    tools: [
      {
        type: 'function',
        function: {
          name: 'get_weather',
          description: 'Get the current weather in a location',
          parameters: {
            type: 'object',
            properties: {
              location: {
                type: 'string',
                description: 'The city and state, e.g. San Francisco, CA'
              },
              unit: {
                type: 'string',
                enum: ['celsius', 'fahrenheit']
              }
            },
            required: ['location']
          }
        }
      }
    ],
    tool_choice: 'auto'
  })
});

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

---

List Available Models

GET https://api.asksage.ai/server/v1/models

Retrieve a list of all available AI models in OpenAI format.

Request Parameters

Authorization string (header) Required

Bearer token authentication: Bearer YOUR_API_KEY

Response Details

200 Success

response (object) - Contains:

• object: "list"
• data: Array of model objects with:
  • id: Model identifier
  • object: "model"
  • created: Creation timestamp
  • owned_by: Model provider

401 Error

Authentication failure

Bash Python JavaScript

curl -X GET 'https://api.asksage.ai/server/v1/models' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'import requests

url = 'https://api.asksage.ai/server/v1/models'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())const response = await fetch('https://api.asksage.ai/server/v1/models', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

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

---

Enhanced Ask Sage Endpoints

Using OpenAI Format with /query

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

The existing /query endpoint now accepts OpenAI message format while remaining backward compatible.

✓ Dual Format Support: Accepts both OpenAI format (messages array) and original Ask Sage format (message string)

Request Parameters

x-access-tokens string (header) Required

24-hour access token or API key for authentication.

messages array Required*

OpenAI-style message array with role and content. Use this OR message parameter.

message string Required*

Original Ask Sage format - a simple string message. Use this OR messages array.

model string Optional

AI model to use (default: "openai_gpt")

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

temperature number Optional

Response randomness (0.0-1.0, default: 0.0)

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

Example: OpenAI Format

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/query' \
  -H 'x-access-tokens: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in simple terms."}
    ]
  }'import requests

url = 'https://api.asksage.ai/server/query'
headers = {
    'x-access-tokens': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': 'Explain quantum computing in simple terms.'}
    ]
}

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_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'Explain quantum computing in simple terms.'}
    ]
  })
});

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

Example: Original Ask Sage Format (Still Supported)

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/query' \
  -H 'x-access-tokens: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "message": "What is machine learning?"
  }'import requests

url = 'https://api.asksage.ai/server/query'
headers = {
    'x-access-tokens': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'message': 'What is machine learning?'
}

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_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    message: 'What is machine learning?'
  })
});

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

Example: Combining OpenAI Format with Ask Sage Parameters

Pro Tip: You can use OpenAI message format AND Ask Sage-specific features like personas, datasets, and live search!

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/query' \
  -H 'x-access-tokens: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Tell me about renewable energy."}
    ],
    "persona": 1,
    "limit_references": 5,
    "live": 1,
    "temperature": 0.7
  }'import requests

url = 'https://api.asksage.ai/server/query'
headers = {
    'x-access-tokens': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'user', 'content': 'Tell me about renewable energy.'}
    ],
    'persona': 1,
    'limit_references': 5,
    'live': 1,
    'temperature': 0.7
}

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_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'user', content: 'Tell me about renewable energy.'}
    ],
    persona: 1,
    limit_references: 5,
    live: 1,
    temperature: 0.7
  })
});

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

---

How It Works

Ask Sage's /v1/* endpoints follow the exact same API specification as OpenAI, making integration seamless.

Using the Same Pattern as OpenAI

You can use Ask Sage's API with the same request/response patterns you're familiar with from OpenAI. Simply point your requests to Ask Sage's base URL with Bearer token authentication.

Key Difference: Instead of using OpenAI's base URL (https://api.openai.com/v1), use Ask Sage's base URL (https://api.asksage.ai/server/v1)

Example: Making Requests

Bash Python JavaScript

# Ask Sage API (OpenAI-compatible format)
curl -X POST 'https://api.asksage.ai/server/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'import requests

# Ask Sage API (OpenAI-compatible format)
url = 'https://api.asksage.ai/server/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4o-mini',
    'messages': [
        {'role': 'user', 'content': 'Hello!'}
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())// Ask Sage API (OpenAI-compatible format)
const response = await fetch('https://api.asksage.ai/server/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {role: 'user', content: 'Hello!'}
    ]
  })
});

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

Same Patterns: Use the same request structure, parameters, and response formats you're already familiar with from OpenAI

---

Migration Guide

Quick Comparison

Feature	OpenAI Endpoints (/v1/*)	Ask Sage Endpoints (/query)
Authentication	Authorization: Bearer KEY	x-access-tokens: KEY
Message Format	OpenAI format only	Both OpenAI and Ask Sage formats
Integration Style	OpenAI-compatible patterns	Ask Sage native patterns
Ask Sage Features	Limited	Full (personas, datasets, live search)
Use Case	Drop-in OpenAI replacement	Full Ask Sage functionality

Key Benefits

Easy Migration

Minimal code changes to switch from OpenAI to Ask Sage

Backward Compatible

Existing Ask Sage code continues to work without changes

Familiar Patterns

Use the same API patterns and structure as OpenAI

Best of Both

Combine OpenAI format with Ask Sage's powerful features