OpenAI-Compatible

OpenAI Compatibility Guide

Seamlessly integrate Ask Sage using the standard OpenAI API format

Table of Contents

1. What’s New?
2. Chat Completions
   1. Request Parameters
   2. Response
   3. Example: Basic Chat Completion
   4. Example: Multi-Turn Conversation
   5. Example: Function Calling
3. Responses API
   1. Request Parameters
   2. Response
   3. Example: Basic Response
   4. Example: Responses with Tools
4. Embeddings
   1. Request Parameters
   2. Response
   3. Example: Single Input
   4. Example: Batch Inputs
5. List Available Models
   1. Request Parameters
   2. Response
   3. Example
6. How It Works
   1. Example: Making Requests
7. Migration Guide

---

Important Note: Base URLs may vary depending on your environment. For assistance, please contact us at support@asksage.ai.

Instance-Specific Base URL: The base URL shown reflects the instance at chat.asksage.ai. The api. prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against.

---

What’s New?

OpenAI Message Format Support

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.

Responses API: Use the newer OpenAI Responses API for stateful, tool-rich conversations.

Embeddings: Generate vector embeddings via the standard /embeddings endpoint.

---

OpenAI-Compatible Endpoints

Chat Completions

Create a Chat Completion

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

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

Authentication: Use a Bearer token in the Authorization header.

Request Parameters

Parameter	Type	Required	Description
Authorization	string (header)	Required	Bearer token: Bearer YOUR_API_KEY
model	string	Required	The AI model to use (e.g., gpt-4.1-mini, claude-35-sonnet)
messages	array	Required	Array of message objects with role (system/user/assistant) and content
temperature	number	Optional	Controls randomness (0.0–2.0). Default: 1.0
max_tokens	integer	Optional	Maximum number of tokens to generate
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	"none", "auto", or specific tool. Default: "auto"

Response

Status	Description
200 Success	Returns id, object (chat.completion), created, model, choices (with index, message, finish_reason), and usage
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/openai/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4.1-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/openai/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4.1-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/openai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1-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/openai/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4.1-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/openai/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4.1-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/openai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1-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

curl -X POST 'https://api.asksage.ai/server/openai/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4.1-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/openai/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4.1-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())

---

Responses API

Create a Response

POST https://api.asksage.ai/server/openai/v1/responses

OpenAI's Responses API — the newer, more flexible endpoint for stateful conversations, advanced tool use, custom tool types, and richer output formats (including reasoning). Use this when your client SDK calls client.responses.create(...) instead of client.chat.completions.create(...).

Authentication: Use a Bearer token in the Authorization header.

When to use Responses vs Chat Completions: Use /responses if your OpenAI SDK client targets the Responses API (e.g. client.responses.create), if you need built-in tool types such as web_search or custom, or if you want server-side reasoning output. For most existing integrations, /chat/completions remains the right choice.

Request Parameters

Parameter	Type	Required	Description
Authorization	string (header)	Required	Bearer token: Bearer YOUR_API_KEY
model	string	Required	The AI model to use (e.g., gpt-5, gpt-4.1-mini)
input	string or array	Required	A plain string prompt, or an array of input items in the OpenAI Responses API format
instructions	string	Optional	System-style instructions prepended to the conversation
tools	array	Optional	Tool definitions — supports function, web_search, and custom types
tool_choice	string or object	Optional	"none", "auto", "required", or a specific tool object
temperature	number	Optional	Controls randomness (0.0–2.0). Default: 1.0
max_output_tokens	integer	Optional	Maximum number of output tokens to generate
stream	boolean	Optional	If true, returns a Server-Sent Events stream. Default: false
reasoning	object	Optional	Reasoning controls for models that support it (e.g., effort level)
metadata	object	Optional	Arbitrary key-value metadata attached to the request

Response

Status	Description
200 Success	Returns id, object (response), created_at, model, output (array of text/tool-call/reasoning items), usage (input_tokens, output_tokens, total_tokens), and status (completed)
400 Error	Invalid request format or missing required parameters
401 Error	Authentication failure — invalid or missing API key
429 Error	Token quota exceeded for the user / plan

Example: Basic Response

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/openai/v1/responses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5",
    "input": "Summarize what Ask Sage is in two sentences."
  }'from openai import OpenAI

client = OpenAI(
    base_url="https://api.asksage.ai/server/openai/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-5",
    input="Summarize what Ask Sage is in two sentences.",
)

print(response.output_text)import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.asksage.ai/server/openai/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-5',
  input: 'Summarize what Ask Sage is in two sentences.',
});

console.log(response.output_text);

Example: Responses with Tools

Bash Python

curl -X POST 'https://api.asksage.ai/server/openai/v1/responses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5",
    "input": "What is the weather in Washington DC today?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto"
  }'from openai import OpenAI

client = OpenAI(
    base_url="https://api.asksage.ai/server/openai/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-5",
    input="What is the weather in Washington DC today?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    }],
    tool_choice="auto",
)

print(response.output)

---

Embeddings

Create Embeddings

POST https://api.asksage.ai/server/openai/v1/embeddings

Generate vector embeddings using the standard OpenAI embeddings format. Works as a drop-in for client.embeddings.create(...) in the OpenAI Python and JavaScript SDKs.

Authentication: Use a Bearer token in the Authorization header.

Supported Models: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002. Other model names fall back to the tenant's default embedding engine.

Input Limits: Maximum 256 inputs per request. Input may be a single string or an array of strings.

Request Parameters

Parameter	Type	Required	Description
Authorization	string (header)	Required	Bearer token: Bearer YOUR_API_KEY
model	string	Optional	Embedding model to use. Default: text-embedding-3-small
input	string or array	Required	The text to embed — a single string or an array of strings (max 256 items)

Response

Status	Description
200 Success	Returns object (list), data (array of {object: "embedding", index, embedding: float[]} items), model, and usage (prompt_tokens, total_tokens)
400 Error	Invalid input format, empty input, or more than 256 inputs
401 Error	Authentication failure — invalid or missing API key
429 Error	Token quota exceeded for the user / plan

Example: Single Input

Bash Python JavaScript

curl -X POST 'https://api.asksage.ai/server/openai/v1/embeddings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Ask Sage is a federally focused AI platform."
  }'from openai import OpenAI

client = OpenAI(
    base_url="https://api.asksage.ai/server/openai/v1",
    api_key="YOUR_API_KEY",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Ask Sage is a federally focused AI platform.",
)

print(response.data[0].embedding[:8])  # first 8 floats
print("total tokens:", response.usage.total_tokens)import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.asksage.ai/server/openai/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Ask Sage is a federally focused AI platform.',
});

console.log(response.data[0].embedding.slice(0, 8));
console.log('total tokens:', response.usage.total_tokens);

Example: Batch Inputs

Bash Python

curl -X POST 'https://api.asksage.ai/server/openai/v1/embeddings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "Ask Sage is a federally focused AI platform.",
      "It provides secure AI tools for government agencies.",
      "Users can query documents and datasets with natural language."
    ]
  }'from openai import OpenAI

client = OpenAI(
    base_url="https://api.asksage.ai/server/openai/v1",
    api_key="YOUR_API_KEY",
)

texts = [
    "Ask Sage is a federally focused AI platform.",
    "It provides secure AI tools for government agencies.",
    "Users can query documents and datasets with natural language.",
]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts,
)

for item in response.data:
    print(f"[{item.index}] {item.embedding[:4]}...")  # first 4 floats

---

List Available Models

List Models

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

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

Request Parameters

Parameter	Type	Required	Description
Authorization	string (header)	Required	Bearer token: Bearer YOUR_API_KEY

Response

Status	Description
200 Success	Returns object: "list" and data array of model objects with id, object, created, owned_by
401 Error	Authentication failure

Example

Bash Python JavaScript

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

url = 'https://api.asksage.ai/server/openai/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/openai/v1/models', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

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

---

How It Works

Same Pattern as OpenAI

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

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/openai/v1).

Example: Making Requests

Bash Python JavaScript

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

# Ask Sage API (OpenAI-compatible format)
url = 'https://api.asksage.ai/server/openai/v1/chat/completions'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-4.1-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/openai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1-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

Key Benefits

Easy Migration: Minimal code changes to switch from OpenAI to Ask Sage.

Familiar Patterns: Use the same API patterns and structure as OpenAI.