Ask Sage Workbooks API

openapi: 3.2.0
info:
  title: Ask Sage User API — Full Response Reference Workbooks 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: Workbooks
  description: Workbook management
paths:
  /workbook:
    put:
      summary: Create workbook
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                  description: Name of the workbook to create; must be longer than 3 and shorter than 500 characters and cannot be the literal 'none' or 'undefined'.
                classification:
                  type:
                  - string
                  - 'null'
                  description: Security classification label applied to the workbook; if omitted or not among the deployment's allowed classifications it falls back to the default, and classifications that require a CAC (e.g. CUI) may be rejected unless the caller is CAC/MFA authorized.
                  default: Unclassified
      responses:
        '200':
          description: Workbook created
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'OK'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot type disabled, server issue, or unhandled service error (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '406':
          description: 'Title too long (>=500 chars) (envelope status 406). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 406
        '407':
          description: 'CAC/CUI-MFA required for the classification (envelope status 407). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 407
        '408':
          description: 'Missing required fields, invalid name, or title too short (envelope status 408). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 408
      operationId: putWorkbook
      x-operation-id-source: derived
    delete:
      summary: Delete workbook
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook to delete; only the owner or an organization admin may delete it.
      responses:
        '200':
          description: Workbook deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'OK'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, server issue, or ''Contact customer support'' service error (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '407':
          description: 'No owner/admin access to delete (envelope status 407). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 407
        '408':
          description: 'Missing required fields, workbook not found (''No workbook.''), or no access (envelope status 408). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 408
      operationId: deleteWorkbook
      x-operation-id-source: derived
  /workbook-chats:
    post:
      summary: Update workbook chats
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              - chats
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook whose stored chat history is being replaced.
                chats:
                  type: array
                  items:
                    type: object
                  description: Array of chat message objects to store on the workbook (replacing any existing chats); recognized per-message fields such as id, message, message_orig, references and follows are HTML-escaped before saving.
      responses:
        '200':
          description: Chats updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'Chats updated'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, missing chats, invalid workbook_id (service), ''Internal error'', or ''Contact customer support'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '408':
          description: 'No access to workbook (envelope status 408). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 408
      operationId: postWorkbookChats
      x-operation-id-source: derived
  /workbook-summary:
    post:
      summary: Update workbook summary
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              - overall_summary
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook whose overall summary is being set.
                overall_summary:
                  type: string
                  description: Summary text to store on the workbook; required and must be non-empty.
      responses:
        '200':
          description: Workbook summary updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'Updated'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, missing summary, invalid workbook_id (service), or ''Contact customer support'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '408':
          description: 'No access to workbook (envelope status 408). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 408
      operationId: postWorkbookSummary
      x-operation-id-source: derived
  /get-workbooks:
    post:
      summary: Get workbooks
      tags:
      - Workbooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                full:
                  type: boolean
                  default: true
                  description: When true, returns full workbook objects (id, title, overall_summary, date_time, classification, chats, user_id); when false, returns only the workbook ids.
      responses:
        '200':
          description: List of workbooks (full objects) or workbook ids (full=false)
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    description: Array of workbook objects when full=true; array of integer workbook ids when full=false
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 123
                        title:
                          type: string
                        overall_summary:
                          type: string
                        date_time:
                          type: string
                          description: Timestamp serialized as string
                          example: '2026-01-01T00:00:00Z'
                        classification:
                          type: string
                        chats:
                          type: string
                          description: JSON-encoded string of chat entries
                        user_id:
                          type: integer
                          example: 123
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled or ''Server issue'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
      operationId: postGetWorkbooks
      x-operation-id-source: derived
  /assign-workbook:
    post:
      summary: Assign workbook to user
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              - email
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook to share; caller must be its owner or an organization admin.
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: Email address of an existing user to grant shared access to the workbook.
      responses:
        '200':
          description: Workbook assigned to user
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'Workbook assigned'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, missing email, ''Internal error'', or ''Contact customer support'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '403':
          description: 'No access to workbook (envelope status 403). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Forbidden
                status: 403
        '404':
          description: 'User not found or workbook not found (envelope status 404). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Not found
                status: 404
        '407':
          description: 'No owner/admin access, or recipient CAC/CUI-MFA required (envelope status 407). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 407
        '408':
          description: 'Workbook already assigned to user (envelope status 408). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 408
      operationId: postAssignWorkbook
      x-operation-id-source: derived
  /deassign-workbook:
    post:
      summary: Remove workbook assignment
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              - email
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook to unshare; caller must be its owner or an organization admin.
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: Email address of the user whose shared access to the workbook is being revoked.
      responses:
        '200':
          description: Workbook assignment removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Literal 'Workbook deassigned'
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, missing email, ''Internal error'', or ''Contact customer support'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '403':
          description: 'No access to workbook (envelope status 403). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Forbidden
                status: 403
        '404':
          description: 'User not found, workbook not found, or shared workbook not found (envelope status 404). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Not found
                status: 404
        '407':
          description: 'No owner/admin access (envelope status 407). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 407
      operationId: postDeassignWorkbook
      x-operation-id-source: derived
  /get-workbook-assignments:
    post:
      summary: Get workbook assignments
      tags:
      - Workbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workbook_id
              properties:
                workbook_id:
                  type: integer
                  description: Numeric id of the workbook whose shared-user assignments (id and email of each user it is shared with) are returned; caller must be its owner or an organization admin.
      responses:
        '200':
          description: List of users assigned to the workbook
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 123
                        email:
                          type: string
                          example: user@example.com
                  status:
                    type: integer
                    example: 200
        '400':
          description: 'Bot disabled, missing/invalid workbook_id, ''Internal error'', or ''Contact customer support'' (envelope status 400). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
        '403':
          description: 'No access to workbook (envelope status 403). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Forbidden
                status: 403
        '404':
          description: 'Workbook not found (envelope status 404). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Not found
                status: 404
        '407':
          description: 'No owner/admin access (envelope status 407). NOTE: this outcome is returned with HTTP 200; the code appears only in the JSON body ''status'' field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Error
                status: 407
      operationId: postGetWorkbookAssignments
      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)