UniversalChatRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/superdocs-app/json-schema/superdocs-app-universal-chat-request-schema.json",
  "title": "UniversalChatRequest",
  "description": "Send a message to the AI assistant with optional document context.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/superdocs-app-openapi.json#/components/schemas/UniversalChatRequest",
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 100000,
      "title": "Message",
      "description": "Your message to the AI assistant."
    },
    "session_id": {
      "type": "string",
      "maxLength": 256,
      "pattern": "^[a-zA-Z0-9_\\-\\.]+$",
      "title": "Session Id",
      "description": "Unique session identifier. Reuse to continue a conversation."
    },
    "document_html": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50000000
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Html",
      "description": "Current document HTML. OMIT this when the session already holds the document — the server persists it across turns, so you don't re-send it every turn; pass it only to load new content or replace the document wholesale (a verbatim load — the AI never re-types content passed here). Include data-chunk-id attributes on elements to enable targeted AI edits."
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "User Id",
      "description": "User identifier. Automatically set from authentication — typically omit this."
    },
    "image_attachments": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/ImageAttachmentData"
          },
          "type": "array",
          "maxItems": 20
        },
        {
          "type": "null"
        }
      ],
      "title": "Image Attachments",
      "description": "Inline images for vision-based analysis (base64-encoded)."
    },
    "model_tier": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Tier",
      "description": "AI model to use: 'core' (default, fast), 'turbo' (fastest), 'pro' (advanced reasoning), 'max' (most capable)."
    },
    "thinking_depth": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Thinking Depth",
      "description": "Reasoning depth: 'fast', 'balanced' (default), or 'deep'. Controls how much analysis the AI performs."
    },
    "approval_mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Approval Mode",
      "description": "Change review mode: 'approve_all' (default, auto-applies changes) or 'ask_every_time' (pauses for your review)."
    },
    "response_mode": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "full",
            "compact"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Response Mode",
      "description": "Response shape control. 'full' (default) returns the complete updated document HTML — required by web app editors and recommended for small documents (<20 pages). 'compact' (recommended for AI agents editing large documents) suppresses the full HTML and returns only per-section diffs (chunk_diffs) for changed sections, saving thousands of tokens per turn. To read sections in compact mode, just send a natural-language request like 'show me the force majeure section' — the AI returns the content in the chat reply text.",
      "default": "full"
    },
    "cursor_context": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cursor Context",
      "description": "Editor cursor context at message time, used to default the insert location for new images, diagrams, or sections when the user's prompt doesn't name a position. Shape: {chunk_id: str, pos_in_chunk?: int, text_before?: str, text_after?: str}. Omit when the user typed in chat without focusing the editor first."
    },
    "document_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Id",
      "description": "Target a specific open document by id (ids come from /v1/sessions/{session_id}/documents). Omit to target the focused document (default — unchanged single-document behaviour). When set, that document becomes the focus for this turn."
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Window Id",
      "description": "Optional identifier for the client window (set by the web app) so concurrent edits from two windows of the same chat are merged rather than overwritten. Agents/API may omit."
    },
    "html_document_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "Html Document Id",
      "description": "Optional: the open document (id from /v1/sessions/{session_id}/documents) that `document_html` is the editor state of. The html is applied to that document only, and a turn that names no `document_id` works on that document by default (it is the one on screen); it does not pin the turn (use `document_id` for that). Set by the web app; omit to mean the focused document."
    },
    "cross_session_memory": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cross Session Memory",
      "description": "When true, the AI carries a private rolling memory of context across THIS account's chats (off by default). Per-request override of your saved Settings default."
    },
    "cross_session_search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cross Session Search",
      "description": "When true, the AI may search your PAST chats and documents on demand to reuse prior work and open a found document (off by default). Per-request override of your saved Settings default; never affects the always-on search of the open document."
    },
    "cross_session_memory_key": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "Cross Session Memory Key",
      "description": "Optional per-request id of YOUR end-customer so the cross-session memory note is kept in a separate file per end-customer. Omit for one account-level note (the default / B2C)."
    },
    "cross_session_scope": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 2000
        },
        {
          "type": "null"
        }
      ],
      "title": "Cross Session Scope",
      "description": "Optional list of session ids to restrict cross-session SEARCH to (e.g. one end-customer's sessions). Omit to search all of this account's sessions. Only narrows within the API-key owner; ignored unless cross_session_search is on."
    },
    "touched_chunk_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 50000
        },
        {
          "type": "null"
        }
      ],
      "title": "Touched Chunk Ids",
      "description": "Optional list of chunk ids (data-chunk-id values) the user actually edited since the last sync, sent alongside document_html. When present, a chunk NOT in this list whose text is unchanged keeps its stored formatting byte-for-byte even if the client serialized it differently (protects styling from editor round-trip loss). Chunks in the list — and any chunk whose text changed — always take the submitted content. Omit for the default behavior (any differing chunk is treated as an edit)."
    },
    "deleted_part_chunk_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 50000
        },
        {
          "type": "null"
        }
      ],
      "title": "Deleted Part Chunk Ids",
      "description": "Optional list of chunk ids (data-chunk-id values) of OUT-OF-FLOW part sections (page headers/footers, footnote/endnote bodies, comments) to delete explicitly, sent alongside document_html. Out-of-flow parts absent from document_html are always KEPT — an editor view not containing them is their normal state, never a deletion — so removing one requires naming its id here. Ids that are not stored out-of-flow parts are ignored (in-flow content keeps the default behavior). Omit when deleting nothing."
    }
  },
  "type": "object",
  "required": [
    "message",
    "session_id"
  ],
  "$defs": {
    "ImageAttachmentData": {
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 256,
          "title": "Id",
          "description": "Unique identifier for this image."
        },
        "name": {
          "type": "string",
          "maxLength": 512,
          "title": "Name",
          "description": "Original filename of the image."
        },
        "base64Data": {
          "type": "string",
          "maxLength": 50000000,
          "title": "Base64Data",
          "description": "Base64-encoded image data."
        },
        "mimeType": {
          "type": "string",
          "maxLength": 128,
          "title": "Mimetype",
          "description": "MIME type (e.g., 'image/png', 'image/jpeg')."
        },
        "size": {
          "type": "integer",
          "maximum": 50000000.0,
          "title": "Size",
          "description": "File size in bytes."
        }
      },
      "type": "object",
      "required": [
        "id",
        "name",
        "base64Data",
        "mimeType",
        "size"
      ],
      "title": "ImageAttachmentData",
      "description": "Inline image attachment for vision-based analysis."
    }
  }
}