Ask Sage User API
User management, authentication and API keys, chat sessions, and dataset permission operations for the Ask Sage platform.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Ask Sage User API",
"description": "Ask Sage User API for account management, organization administration, billing, and platform configuration.\n\n## Base URL\n`https://api.asksage.ai/user`\n\n## Authentication\nAll endpoints require a valid JWT token passed via the `x-access-tokens` header, unless otherwise noted.\n\nObtain a token using `/get-token-with-api-key` with your email and API key.\n\n## Key Features\n- **User Management** \u2014 Profile updates, API key management, login history\n- **Chat Sessions** \u2014 Create, retrieve, and manage conversation history\n- **Dataset Management** \u2014 Create datasets, manage permissions and assignments\n- **Workbooks** \u2014 Organize research with sources and memos\n- **Organization Admin** \u2014 User management, token allocation, usage reporting\n- **Superadmin** \u2014 Platform-wide administration and analytics",
"version": "2.0",
"contact": {
"name": "Ask Sage Support",
"email": "support@asksage.ai",
"url": "https://asksage.ai"
}
},
"servers": [
{
"url": "{baseUrl}/user",
"description": "Ask Sage User 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": []
}
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-access-tokens",
"description": "JWT authentication token. Obtain a token by calling `/get-token-with-api-key` with your email and 64-character API key. Some admin and superadmin endpoints also require an email address in the request body to identify the target user."
}
},
"schemas": {
"Dataset": {
"type": "object",
"properties": {
"dataset": {
"type": "string"
},
"classification": {
"type": "string",
"enum": [
"Unclassified",
"CUI"
]
},
"permissions": {
"type": "string",
"enum": [
"read",
"edit",
"admin",
"owner"
]
}
}
},
"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": {
"type": "integer",
"format": "int64"
},
"expiration": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"paths": {
"/get-token-with-api-key": {
"post": {
"summary": "Get token using API key",
"tags": [
"Authentication"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email",
"api_key"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"api_key": {
"type": "string",
"minLength": 64,
"maxLength": 64
}
}
}
}
}
},
"responses": {
"200": {
"description": "Token generated successfully"
}
}
}
},
"/get-chats": {
"post": {
"summary": "Get all chat sessions for user",
"tags": [
"Chat Management"
],
"responses": {
"200": {
"description": "Chat sessions retrieved",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string",
"description": "JSON string containing chats and buttons arrays"
}
}
}
}
}
}
}
}
},
"/get-chat-session": {
"post": {
"summary": "Get specific chat session",
"tags": [
"Chat Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Chat session retrieved"
}
}
}
},
"/delete-chat-session": {
"post": {
"summary": "Delete chat session",
"tags": [
"Chat Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Chat session deleted"
}
}
}
},
"/add-dataset": {
"post": {
"summary": "Add dataset to user",
"tags": [
"Dataset Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"dataset"
],
"properties": {
"dataset": {
"type": "string",
"minLength": 4,
"maxLength": 100
},
"classification": {
"type": "string",
"enum": [
"Unclassified",
"CUI"
]
},
"is_tabular": {
"type": "boolean",
"default": false,
"description": "Whether this is a tabular dataset"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Dataset added"
}
}
}
},
"/assign-dataset": {
"post": {
"summary": "Assign dataset to user",
"tags": [
"Dataset Management"
],
"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"
}
}
}
},
"/deassign-dataset": {
"post": {
"summary": "Remove dataset from user",
"tags": [
"Dataset Management"
],
"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 deassigned"
}
}
}
},
"/update-permission-dataset": {
"post": {
"summary": "Update dataset permissions",
"tags": [
"Dataset Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"dataset",
"email"
],
"properties": {
"dataset": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"permissions": {
"type": "string",
"enum": [
"read",
"edit",
"admin"
],
"default": "read"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Permissions updated"
}
}
}
},
"/get-datasets-with-permissions": {
"post": {
"summary": "Get user datasets with permissions",
"tags": [
"Dataset Management"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"check_permissions": {
"type": "boolean",
"default": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Datasets retrieved",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Dataset"
}
}
}
}
}
}
}
}
},
"get": {
"summary": "Get user datasets with permissions (GET)",
"tags": [
"Dataset Management"
],
"responses": {
"200": {
"description": "Datasets retrieved",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Dataset"
}
}
}
}
}
}
}
}
}
},
"/get-user-logs": {
"post": {
"summary": "Get user activity logs",
"tags": [
"User Information"
],
"responses": {
"200": {
"description": "Logs retrieved"
}
}
}
},
"/get-user-logins": {
"post": {
"summary": "Get user login history",
"tags": [
"User Information"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 5
}
}
}
}
}
},
"responses": {
"200": {
"description": "Login history retrieved"
}
}
}
},
"/get-user-api-keys": {
"post": {
"summary": "Get user API keys",
"tags": [
"API Key Management"
],
"responses": {
"200": {
"description": "API keys retrieved"
}
}
}
},
"/user-api-key": {
"post": {
"summary": "Create new API key",
"tags": [
"API Key Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "API key created"
}
}
},
"delete": {
"summary": "Delete API key",
"tags": [
"API Key Management"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "API key deleted"
}
}
}
},
"/admin-total-purchased-tokens-organization": {
"post": {
"summary": "Get total purchased tokens for organization",
"tags": [
"Admin"
],
"responses": {
"200": {
"description": "Token information retrieved"
}
}
}
},
"/admin-used-tokens-for-organization": {
"post": {
"summary": "Get used tokens for organization",
"tags": [
"Admin"
],
"responses": {
"200": {
"description": "Used tokens retrieved"
}
}
}
},
"/admin-get-dataset": {
"post": {
"summary": "Get datasets for user (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Datasets retrieved"
}
}
}
},
"/admin-export-users-csv": {
"post": {
"summary": "Export organization users to CSV",
"tags": [
"Admin"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"full": {
"type": "boolean",
"default": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "CSV file",
"content": {
"text/csv": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/admin-update-user-verified": {
"post": {
"summary": "Verify user email (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User verified"
}
}
}
},
"/admin-update-user-paid": {
"post": {
"summary": "Update user paid status (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"paid": {
"type": "integer",
"enum": [
0,
1
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Paid status updated"
}
}
}
},
"/admin-update-user-banned": {
"post": {
"summary": "Ban/unban user (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"banned": {
"type": "integer",
"enum": [
0,
1
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ban status updated"
}
}
}
},
"/admin-update-user-tokens": {
"post": {
"summary": "Update user token limit (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"tokens": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Tokens updated"
}
}
}
},
"/admin-update-user-train-tokens": {
"post": {
"summary": "Update user training token limit (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"tokens": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Training tokens updated"
}
}
}
},
"/admin-get-token-stats": {
"post": {
"summary": "Get token usage statistics (admin)",
"tags": [
"Admin"
],
"responses": {
"200": {
"description": "Statistics retrieved"
}
}
}
},
"/admin-get-user-count": {
"post": {
"summary": "Get user count for organization (admin)",
"tags": [
"Admin"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"paid": {
"type": "boolean"
},
"hide_banned": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User count retrieved"
}
}
}
},
"/admin-get-all-users-with-tokens": {
"post": {
"summary": "Get all organization users with token info (admin)",
"tags": [
"Admin"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"full": {
"type": "boolean"
},
"start": {
"type": "integer"
},
"limit": {
"type": "integer",
"default": 500
},
"email": {
"type": "string"
},
"sort_by": {
"type": "string",
"enum": [
"id",
"organization_id",
"type",
"first_name",
"last_name",
"phone",
"email",
"company",
"paid",
"max_tokens",
"max_train_tokens",
"banned",
"email_verified",
"country",
"mfa_secret",
"x509_cn"
]
},
"sort_direction": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Users retrieved"
}
}
}
},
"/admin-get-all-logs": {
"post": {
"summary": "Get user logs (admin)",
"tags": [
"Admin"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user_id"
],
"properties": {
"user_id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Logs retrieved"
}
}
}
},
"/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",
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ask-sage/refs/heads/main/openapi/ask-sage-user-openapi.json