The Ask Sage API is a modern RESTful API providing comprehensive access to the Ask Sage platform. Our API architecture is divided into two specialized components, each designed for specific functionalities — the Server API and the User API. Each has its own base URL, purpose, and set of endpoints.
The Server API focuses on core AI operations, model queries, and server management, while the User API handles user management, authentication, and dataset operations. This separation ensures optimized performance and security for different types of interactions with the Ask Sage platform.
User API
User API Endpoints
Purpose & Base URL
User management, authentication, and dataset operations.
BASEapi.{instance}.ai/user/
Instance-Specific Base URL: The base URL shown reflects the instance at chat.asksage.ai. The api. prefix and /user/ 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.
Scoped API Keys: If you’re calling these endpoints with a scoped API key, make sure the key includes the scope that covers the endpoint you need — see Restricting Access with Scopes.
Available Endpoints
Method
Endpoint
Description
POST
/get-token-with-api-key
Get an access token with API Key and email
POST
/get-user-logins
Get your last logins (limited to 5 by default)
POST
/get-user-logs
Get your last prompts
POST
/add-dataset
Add a new dataset
POST
/delete-datasets
Delete a dataset
POST
/get-chats
Get all chat sessions for user
POST
/get-chat-session
Get specific chat session
POST
/delete-chat-session
Delete chat session
POST
/deassign-dataset
Remove dataset from user
POST
/update-permission-dataset
Update dataset permissions
POST
/get-datasets-with-permissions
Get user datasets with permissions
POST
/get-user-api-keys
Get user API keys
POST
/user-api-key
Create new API key
DELETE
/user-api-key
Delete API key
Organization Policies (Administrators)
Organization administrators can read and change their organization’s policies, such as whether MFA is required, whether API keys are enabled and which scopes they may use, the default member role, and default token limits. The admin- routes always act on the caller’s own organization; the superadmin- routes take an organization ID.
Method
Endpoint
Description
POST
/admin-get-organization-policies
Get every policy for your organization, with its source and whether it can be changed
POST
/admin-update-organization-policy
Set one policy (policy_key, policy_value) for your organization
POST
/admin-reset-organization-policy
Reset one policy (policy_key) to the tenant default
POST
/superadmin-get-organization-policies/{org_id}
Superadmin: get every policy for any organization
POST
/superadmin-update-organization-policy/{org_id}
Superadmin: set one policy for any organization
POST
/superadmin-reset-organization-policy/{org_id}
Superadmin: reset one policy for any organization
For example, to require MFA for your organization, send {"policy_key": "mfa_enrollment_required", "policy_value": true} to /admin-update-organization-policy. Members without MFA then set it up at their next sign-in; members using SSO or a CAC / smart card aren’t affected. While MFA is required for the whole deployment, this key can’t be changed and the request returns 409. Every change is recorded in the policy audit log.
See the Swagger reference for the full request and response schemas.
Server API
Server API Endpoints
Purpose & Base URL
Core AI operations, model queries, and server management.
BASEapi.{instance}.ai/server/
Instance-Specific Base URL: The base URL shown reflects the instance at chat.asksage.ai. The api. prefix and /server/ 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.
Generate audio from text using TTS (up to 20,000 characters by default)
GET
/list-agents
Returns a list of all agents available to the user (paid accounts)
POST
/execute-agent
Execute an agent with a message and optional variables (paid accounts)
Provider-Compatible Endpoints
Ask Sage also exposes the wire formats of the major model providers under /server/, so existing SDKs and tools work by changing only the base URL and key. These routes accept the same Ask Sage API key as a Bearer token.
Each example below includes Bash, Python, and JavaScript code stacked sequentially. Replace your_access_token with a valid token obtained from the Get Access Token endpoint.
Authentication
Get Access Token
Authenticate with your API key to receive an access token for subsequent requests.
Optional token_scopes: Pass a comma-separated string (e.g. "query,mcp") to restrict the key to specific surfaces; any invalid scope returns 400. Valid values: query, agent_builder, passthrough, mcp. Omit it to create an unscoped key.
Send a message to an AI model and receive a response. This is the primary endpoint for interacting with Ask Sage.
Advanced deep-agent fields:video_options, prior_deep_agent_ids, and skip_search are accepted only via multipart/form-data (the same form used for file uploads), not in the JSON body shown below.
Retrieve the list of AI models available to your account.
Optional format query parameter: Add ?format=full to return the enriched model objects (with metadata) instead of the default key list. Works on both GET and POST.
Agent Builder endpoints, including the agent endpoints below, are available to paid accounts. Accounts that aren’t paid receive 404 Not found, except that owners can still delete their own workflows and agents.
Execute Agent
Execute an AI agent with a message and optional variables. Supports non-streaming, streaming, and file-upload modes.