OpenAPI Specification
openapi: 3.0.3
info:
title: Ask Sage Server Admin Superadmin API
description: 'Ask Sage is an AI-powered platform providing intelligent completions, knowledge management, and workflow automation.
## Base URL
`https://api.asksage.ai`
## Authentication
All endpoints require a valid JWT token passed via the `x-access-tokens` header, unless otherwise noted.
Obtain a token by authenticating through the User API (`/user/get-token-with-api-key`).
## Message Format
The `message` field in API requests can be either:
- A single string prompt: `"What is Ask Sage?"`
- An array of conversation messages: `[{"user": "me", "message": "what is Ask Sage?"}, {"user": "gpt", "message": "Ask Sage is an..."}]`
## Key Features
- **AI Completions** — Query multiple LLM providers with a unified interface
- **Knowledge Training** — Upload documents, files, and data to build custom datasets
- **Tabular Data** — Ingest and query structured data (CSV, XLSX) with natural language
- **Agent Builder** — Create, configure, and execute multi-step AI workflows
- **Plugins** — Extend capabilities with built-in and custom plugins
- **MCP Servers** — Connect to Model Context Protocol servers for tool integration'
version: '2.0'
contact:
name: Ask Sage Support
email: support@asksage.ai
url: https://asksage.ai
servers:
- url: '{baseUrl}/server'
description: Ask Sage Server API
variables:
baseUrl:
default: https://api.asksage.ai
description: API base URL. Use https://api.asksage.ai for production, or your self-hosted instance URL.
security:
- ApiKeyAuth: []
tags:
- name: Superadmin
description: Superadmin system operations
paths:
/superadmin-get-all-users-with-tokens:
post:
summary: Get all users with token info (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
full:
type: boolean
paid:
type: boolean
start:
type: integer
limit:
type: integer
default: 100
hide_banned:
type: boolean
email:
type: string
organization_id:
type: integer
sort_by:
type: string
sort_direction:
type: string
responses:
'200':
description: Users retrieved
/superadmin-export-users-csv:
post:
summary: Export all users to CSV (superadmin)
tags:
- Superadmin
responses:
'200':
description: CSV file
content:
text/csv:
schema:
type: string
/superadmin-get-users:
post:
summary: Get users (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
start:
type: integer
limit:
type: integer
email:
type: string
responses:
'200':
description: Users retrieved
/superadmin-get-user-count:
post:
summary: Get total user count (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
paid:
type: boolean
hide_banned:
type: boolean
organization_id:
type: integer
responses:
'200':
description: User count retrieved
/superadmin-get-stats:
post:
summary: Get system statistics (superadmin)
tags:
- Superadmin
responses:
'200':
description: Statistics retrieved
/superadmin-get-token-stats:
post:
summary: Get token usage statistics (superadmin)
tags:
- Superadmin
responses:
'200':
description: Token statistics retrieved
/superadmin-get-all-logs:
post:
summary: Get system logs (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
type: integer
limit:
type: integer
default: 100
responses:
'200':
description: Logs retrieved
/superadmin-update-user-verified:
post:
summary: Verify user email (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
responses:
'200':
description: User verified
/superadmin-update-user-banned:
post:
summary: Ban/unban user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
banned:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Ban status updated
/superadmin-update-user-paid:
post:
summary: Update user paid status (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
paid:
type: integer
enum:
- 0
- 1
testing:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Paid status updated
/superadmin-update-user-admin:
post:
summary: Grant/revoke admin privileges (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
admin:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Admin status updated
/superadmin-update-user-tokens:
post:
summary: Update user token limit (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
tokens:
type: integer
responses:
'200':
description: Tokens updated
/superadmin-update-user-train-tokens:
post:
summary: Update user training token limit (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
tokens:
type: integer
responses:
'200':
description: Training tokens updated
/superadmin-change-email:
post:
summary: Change user email (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- old_email
- new_email
properties:
old_email:
type: string
format: email
new_email:
type: string
format: email
responses:
'200':
description: Email changed
/superadmin-assign-payer:
post:
summary: Assign payer email to user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_email
- payer_email
properties:
user_email:
type: string
format: email
payer_email:
type: string
format: email
responses:
'200':
description: Payer assigned
/superadmin-deassign-organization:
post:
summary: Remove user from organization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_email
properties:
user_email:
type: string
format: email
responses:
'200':
description: Organization removed
/superadmin-cuimfa:
post:
summary: Enable/disable CUI MFA authorization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_email
- enable
properties:
user_email:
type: string
format: email
enable:
type: integer
enum:
- 0
- 1
responses:
'200':
description: CUI MFA status updated
/superadmin-delete-last-chatsession:
post:
summary: Delete user's last chat session (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Chat session deleted
/superadmin-reset-mfa:
post:
summary: Reset user MFA (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: MFA reset
/superadmin-reset-cac:
post:
summary: Reset user CAC (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: CAC reset
/superadmin-reset-pw:
post:
summary: Reset user password (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Password reset
content:
application/json:
schema:
type: object
properties:
response:
type: string
new_password:
type: string
status:
type: integer
/superadmin-assign-dataset:
post:
summary: Assign dataset to user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dataset
- email
properties:
dataset:
type: string
email:
type: string
format: email
responses:
'200':
description: Dataset assigned
/superadmin-deassign-dataset:
post:
summary: Remove dataset from user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dataset
- email
properties:
dataset:
type: string
email:
type: string
format: email
responses:
'200':
description: Dataset removed
/superadmin-get-dataset:
post:
summary: Get user datasets (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Datasets retrieved
/superadmin-delete-all-dataset:
post:
summary: Delete dataset from all users (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dataset
properties:
dataset:
type: string
responses:
'200':
description: Dataset deleted
/superadmin-assign-persona:
post:
summary: Assign persona to user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- persona_id
properties:
email:
type: string
format: email
persona_id:
type: integer
responses:
'200':
description: Persona assigned
/superadmin-assign-plugin:
post:
summary: Assign plugin to user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- plugin_name
properties:
email:
type: string
format: email
plugin_name:
type: string
pattern: ^[A-Za-z_]+$
responses:
'200':
description: Plugin assigned
/superadmin-get-user-api-keys:
post:
summary: Get user API keys (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
format: email
responses:
'200':
description: API keys retrieved
/superadmin-user-api-key:
post:
summary: Create API key for user (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
email:
type: string
format: email
name:
type: string
default: default
responses:
'200':
description: API key created
/superadmin-get-all-organizations:
post:
summary: Get all organizations (superadmin)
tags:
- Superadmin
responses:
'200':
description: Organizations retrieved
/superadmin-add-organization:
post:
summary: Add new organization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- point_contact
- country
- email
properties:
name:
type: string
point_contact:
type: string
address:
type: string
zip:
type: string
city:
type: string
country:
type: string
phone:
type: string
email:
type: string
format: email
domainname:
type: string
force_models:
type: string
responses:
'200':
description: Organization added
/superadmin-update-organization/{organization_id}:
put:
summary: Update organization (superadmin)
tags:
- Superadmin
parameters:
- in: path
name: organization_id
schema:
type: integer
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
responses:
'200':
description: Organization updated
/superadmin-get-organization/{organization_id}:
get:
summary: Get organization details (superadmin)
tags:
- Superadmin
parameters:
- in: path
name: organization_id
schema:
type: integer
required: true
responses:
'200':
description: Organization retrieved
/superadmin-assign-users-to-organization:
post:
summary: Assign users to organization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
- emails
properties:
organization_id:
type: integer
emails:
type: array
items:
type: string
format: email
responses:
'200':
description: Users assigned
/superadmin-add-organization-purchase:
post:
summary: Add organization purchase (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- date_purchase
- email_payer
- total_tokens
- total_training_tokens
- expiration
- organization_id
properties:
date_purchase:
type: string
format: date
email_payer:
type: string
format: email
payer_comment:
type: string
total_tokens:
type: integer
total_training_tokens:
type: integer
expiration:
type: string
format: date
organization_id:
type: integer
responses:
'200':
description: Purchase added
/superadmin-update-organization-purchase/{purchase_id}:
put:
summary: Update organization purchase (superadmin)
tags:
- Superadmin
parameters:
- in: path
name: purchase_id
schema:
type: integer
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPurchase'
responses:
'200':
description: Purchase updated
/superadmin-get-organization-purchases/{organization_id}:
post:
summary: Get organization purchases (superadmin)
tags:
- Superadmin
parameters:
- in: path
name: organization_id
schema:
type: integer
required: true
responses:
'200':
description: Purchases retrieved
/superadmin-update-sales:
post:
summary: Import sales data from Excel (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: Excel file with organizations, organization_purchases, and users sheets
responses:
'200':
description: Sales data imported
/superadmin-export-weekly-reports:
post:
summary: Export weekly organization report (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
monthly:
type: boolean
default: false
responses:
'200':
description: CSV report generated
content:
text/csv:
schema:
type: string
/superadmin-export-weekly-model-usage-csv:
post:
summary: Export model usage report (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
monthly:
type: boolean
default: false
responses:
'200':
description: CSV report generated
content:
text/csv:
schema:
type: string
/superadmin-allocation-policy-get:
post:
summary: Get allocation policy (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
organization_id:
type: integer
responses:
'200':
description: Policy retrieved
/superadmin-allocation-policy-update:
post:
summary: Update allocation policy (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
strategy:
type: string
percentage:
type: number
fixed_amount:
type: integer
responses:
'200':
description: Policy updated
/superadmin-token-distribution-preview:
post:
summary: Preview token distribution (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
responses:
'200':
description: Distribution preview
/superadmin-token-distribution-execute:
post:
summary: Execute token distribution (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
responses:
'200':
description: Distribution executed
/superadmin-allocation-dashboard:
post:
summary: Get allocation dashboard (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
responses:
'200':
description: Dashboard data retrieved
/superadmin-get-all-datasets:
post:
summary: Get all datasets (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
organization_id:
type: integer
limit:
type: integer
default: 100
offset:
type: integer
default: 0
search:
type: string
sort_by:
type: string
sort_direction:
type: string
enum:
- asc
- desc
responses:
'200':
description: Datasets retrieved
/superadmin-get-dataset-files:
post:
summary: Get dataset files (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dataset_id
properties:
dataset_id:
type: integer
limit:
type: integer
offset:
type: integer
responses:
'200':
description: Dataset files retrieved
/superadmin-get-dataset-statistics:
post:
summary: Get dataset statistics (superadmin)
tags:
- Superadmin
responses:
'200':
description: Dataset statistics retrieved
/superadmin-get-dataset-details:
post:
summary: Get dataset details (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dataset_id
properties:
dataset_id:
type: integer
responses:
'200':
description: Dataset details retrieved
/superadmin-export-datasets-csv:
post:
summary: Export datasets to CSV (superadmin)
tags:
- Superadmin
responses:
'200':
description: CSV file
content:
text/csv:
schema:
type: string
/superadmin-get-analytics-data:
post:
summary: Get analytics data (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
organization_id:
type: integer
start_date:
type: string
format: date
end_date:
type: string
format: date
responses:
'200':
description: Analytics data retrieved
/superadmin-export-label-usage-csv:
post:
summary: Export label usage to CSV (superadmin)
tags:
- Superadmin
responses:
'200':
description: CSV file
content:
text/csv:
schema:
type: string
/superadmin-get-token-requests:
post:
summary: Get token requests (superadmin)
tags:
- Superadmin
requestBody:
content:
application/json:
schema:
type: object
properties:
organization_id:
type: integer
status:
type: string
limit:
type: integer
offset:
type: integer
responses:
'200':
description: Token requests retrieved
/superadmin-review-token-request:
post:
summary: Review token request (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- request_id
- action
properties:
request_id:
type: integer
action:
type: string
enum:
- approve
- deny
approved_amount:
type: integer
admin_note:
type: string
responses:
'200':
description: Token request reviewed
/superadmin-total-purchased-tokens-organization:
post:
summary: Get total purchased tokens for organization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
responses:
'200':
description: Token information retrieved
/superadmin-used-tokens-for-organization:
post:
summary: Get used tokens for organization (superadmin)
tags:
- Superadmin
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- organization_id
properties:
organization_id:
type: integer
responses:
'200':
description: Used tokens retrieved
components:
schemas:
Organization:
type: object
properties:
id:
type: integer
name:
type: string
point_contact:
type: string
address:
type: string
zip:
type: string
city:
type: string
country:
type: string
phone:
type: string
email:
type: string
domainname:
type: string
force_models:
type: string
settings:
type: string
OrganizationPurchase:
type: object
properties:
id:
type: integer
organization_id:
type: integer
date_purchase:
type: string
format: date-time
email_payer:
type: string
payer_comment:
type: string
total_tokens:
type: integer
format: int64
total_training_tokens:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ask-sage/refs/heads/main/openapi/ask-sage-superadmin-api-openapi.yml