Ask Sage User Management API

openapi: 3.2.0
info:
  title: Ask Sage User API — Full Response Reference User Management…
  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: User Management
  description: User profile and settings management
paths:
  /register:
    post:
      summary: Register new user
      tags:
      - User Management
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - first_name
              - last_name
              - company
              - email
              - password
              - country
              properties:
                first_name:
                  type: string
                  description: The user's given name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped before storage.
                last_name:
                  type: string
                  description: The user's family name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped before storage.
                company:
                  type: string
                  description: The user's organization or company name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped before storage.
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: The account email address; required, lowercased and normalized, must be a valid address, must pass any configured domain allow/block list, and must not already be registered. A six-digit email verification code is sent to it.
                password:
                  type: string
                  description: The account password; required unless SSO is enforced. On standard tenants it must be at least 9 characters with at least one number and one special character; on DoD/CIV or complexity-enforcing tenants it must be at least 15 characters with an uppercase letter, a lowercase letter, a number, and a special character.
                  minLength: 9
                country:
                  type: string
                  description: The user's country of residence; required and must be one of the approved (largely US/NATO/allied) countries or registration is refused.
                  enum:
                  - United States
                  - United Kingdom
                  - Canada
                  - Australia
                  - New Zealand
                  - Belgium
                  - Bulgaria
                  - Czech Republic
                  - Denmark
                  - Germany
                  - Estonia
                  - Ireland
                  - India
                  - Greece
                  - Spain
                  - Singapore
                  - Japan
                  - France
                  - Croatia
                  - Italy
                  - Cyprus
                  - Latvia
                  - Lithuania
                  - Luxembourg
                  - Hungary
                  - Malta
                  - Netherlands
                  - Austria
                  - Poland
                  - Portugal
                  - Romania
                  - Slovenia
                  - Slovakia
                  - Saudi Arabia
                  - Sweden
                  - Finland
                  - Iceland
                  - Norway
                  - Liechtenstein
                  - Switzerland
                phone:
                  type: string
                  description: The user's phone number; optional.
                  default: ''
                signup_code:
                  type: string
                  description: Optional signup/invitation code
                captcha_token:
                  type: string
                  description: The Google reCAPTCHA response token from the client challenge; required only when CAPTCHA is enabled for the tenant and validated server-side against Google's siteverify API.
      responses:
        '200':
          description: User registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: '''Success'' on registration'
                  verified:
                    type: boolean
                    description: Whether the email was auto-verified
                  status:
                    type: integer
                    example: 200
        '400':
          description: Validation/registration error (SSO required, CAPTCHA required or failed, missing required fields, invalid characters, invalid or non-whitelisted/blacklisted email domain, unsupported country, email already exists, or password complexity failure). Envelope {'response':<message or complexity object>,'status':400}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
      operationId: postRegister
      x-operation-id-source: derived
  /update:
    post:
      summary: Update user profile
      tags:
      - User Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - first_name
              - last_name
              - company
              - password
              properties:
                first_name:
                  type: string
                  description: Updated given name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped.
                last_name:
                  type: string
                  description: Updated family name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped.
                company:
                  type: string
                  description: Updated organization or company name; required. Structural characters (; [ ] < >) are rejected and HTML tags plus unsafe unicode are stripped.
                password:
                  type: string
                  description: New password (empty string to keep current)
                phone:
                  type: string
                  description: Updated phone number; optional.
                  default: ''
                custom_intro_prompt:
                  type: string
                  description: Custom intro prompt (paid users only)
                current_password:
                  type: string
                  description: The user's existing password, required to re-authenticate when changing to a new password (not required during a forced password-reset flow); the change is rejected if it does not match the stored password.
                  default: ''
                mfa_code:
                  type: string
                  description: The current TOTP code from the user's authenticator app, required to change the password when the account has finalized MFA enabled; the change is rejected if the code is invalid.
                  default: ''
      responses:
        '200':
          description: Profile updated (optionally password changed and all sessions revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                  password_changed:
                    type: boolean
                    description: Present and true only when the password was changed
                  status:
                    type: integer
                    example: 200
        '400':
          description: Validation error (bot account disabled, no data provided, missing required fields, current password required/incorrect, MFA code required/incorrect, password complexity object, or password reuse).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '500':
          description: Internal error. Envelope {'response':'Internal Error','status':500}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Internal server error
                status: 500
      operationId: postUpdate
      x-operation-id-source: derived
  /verify-email:
    post:
      summary: Verify email address
      tags:
      - User Management
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: user@example.com
                  description: The email address of the account to verify; matched case-insensitively against the registered user.
                verification_code:
                  type: string
                  description: The six-digit code emailed to the user at registration; must match the account's stored code to mark the email as verified.
              required:
              - email
              - verification_code
      responses:
        '200':
          description: Email verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: '''Validated'''
                  status:
                    type: string
                    example: '200'
        '400':
          description: SSO required, invalid email, invalid verification code, or bot account disabled. Envelope {'response':<message>,'status':'400'}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
      operationId: postVerifyEmail
      x-operation-id-source: derived
  /lost-pass:
    post:
      summary: Request password reset
      tags:
      - User Management
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: Email address of the account to send a password-reset link to; lowercased before lookup (the endpoint always returns success even if no matching account exists).
      responses:
        '200':
          description: Reset request accepted (returned whether or not the email exists)
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: '''Success'''
                  status:
                    type: string
                    example: '200'
        '400':
          description: SSO required, bot account disabled, or internal error. Envelope {'response':<message>,'status':400 or '400'}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
      operationId: postLostPass
      x-operation-id-source: derived
  /update-mfa:
    post:
      summary: Enable or update MFA
      tags:
      - User Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: The current six-digit TOTP code from the user's authenticator app, used to confirm and finalize MFA enrollment; enrollment succeeds only if the code matches the pending MFA secret.
              required:
              - code
      responses:
        '200':
          description: MFA finalized
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: '''OK'''
                  status:
                    type: integer
                    example: 200
        '400':
          description: SSO required, bot account disabled, or server issue (missing/invalid MFA secret).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '401':
          description: MFA already set. Envelope {'response':'Already set','status':401} (HTTP body carries 200 with status field 401).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Unauthorized
                status: 401
        '402':
          description: Empty or wrong verification code. Envelope {'response':'Empty code'|'Wrong code','status':402}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Payment required
                status: 402
      operationId: postUpdateMfa
      x-operation-id-source: derived
  /logout:
    post:
      summary: Logout user
      tags:
      - User Management
      responses:
        '200':
          description: Logged out; token revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: '''Logged out'''
                  status:
                    type: integer
                    example: 200
        '400':
          description: Bot account disabled. Envelope {'response':'Disabled.','status':400}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '500':
          description: Internal error. Envelope {'response':'Internal Error','status':500}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Internal server error
                status: 500
      parameters:
      - name: x-access-tokens
        in: header
        required: false
        schema:
          type: string
        description: The access token to revoke (the same token used to authenticate the request).
      operationId: postLogout
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard Ask Sage error envelope.
      properties:
        response:
          type: string
          description: Human-readable error message.
        status:
          type: integer
          example: 400
          description: HTTP-style status code (usually an integer; some endpoints return it as a numeric string).
  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)