Ask Sage System API

openapi: 3.2.0
info:
  title: Ask Sage User API — Full Response Reference System API
  description: 'Ask Sage User API for account management, organization administration, billing, and platform configuration.


    ## Base URL

    `https://api.asksage.ai/user`


    ## Authentication

    Most endpoints require a valid JWT token sent in the `x-access-tokens` HTTP header. Secured endpoints show a padlock in Swagger UI / Redoc — click **Authorize** and paste your token once to apply it to every request.


    Get a token from `/get-token-with-api-key` (your email + 64-character API key), then send it on each call:


    `x-access-tokens: `


    **No token required:** `/get-token-with-api-key`, `/register`, `/verify-email`, `/lost-pass`, and `GET /get-headers`.


    Beyond a valid token, admin (`admin-*`) and superadmin (`superadmin-*`) endpoints require the caller to hold the matching role, and many identify the target user via an `email` field in the request body.

    ## Key Features

    - **User Management** — Profile updates, API key management, login history

    - **Chat Sessions** — Create, retrieve, and manage conversation history

    - **Dataset Management** — Create datasets, manage permissions and assignments

    - **Workbooks** — Organize research with sources and memos

    - **Organization Admin** — User management, token allocation, usage reporting

    - **Superadmin** — Platform-wide administration and analytics'
  version: '2.0'
  contact:
    name: 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: []
tags:
- name: System
  description: System utilities and health checks
paths:
  /get-headers:
    get:
      summary: Debug endpoint to view request headers
      tags:
      - System
      security: []
      responses:
        '200':
          description: HTML dump of the incoming request headers
          content:
            text/html:
              schema:
                type: string
      operationId: getGetHeaders
      x-operation-id-source: derived
    post:
      summary: Debug endpoint to view request headers
      tags:
      - System
      security: []
      responses:
        '200':
          description: Headers displayed
      operationId: postGetHeaders
      x-operation-id-source: derived
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.
x-provenance:
  method: harvested
  publisher: Ask Sage
  source: https://docs.asksage.ai/api-docs/specs/user-api-spec.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)