superdocs-app Documents API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Documents API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Documents
paths:
  /v1/documents/upload:
    post:
      tags:
      - Documents
      summary: Upload Document To Editor
      description: 'Upload a document file and load it into the editor.


        Converts the file to HTML with formatting preserved (tables, colors, images).

        Images are extracted to cloud storage and referenced by URL.

        Returns the HTML for the editor to display.


        AI indexing happens automatically on the first chat message.

        For API clients who want immediate indexing, pass ?index=true.'
      operationId: upload_document_to_editor
      security:
      - HTTPBearer: []
      parameters:
      - name: index
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Set to ''true'' for immediate AI indexing (API clients). Default: conversion only.'
          title: Index
        description: 'Set to ''true'' for immediate AI indexing (API clients). Default: conversion only.'
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_document_to_editor'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/documents/images/upload:
    post:
      tags:
      - Documents
      summary: Upload an image and get back a stable URL the editor can drop into
      description: 'Upload a single inline image and return a URL you can reference

        in the document via .


        Accepts PNG/JPEG/WebP/GIF/SVG, up to 10 MB per upload. The returned `url`

        is a time-limited signed link (image storage is private; images are always

        served via signed URLs) that renders immediately in the editor; on save the

        backend normalizes it to the stable canonical reference, and every

        subsequent read re-signs it fresh. `canonical_url` is that stable stored

        form. Useful for saving a drawing or screenshot so a document can embed it.'
      operationId: upload_inline_image
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_inline_image'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/documents/export/email-request:
    post:
      tags:
      - Documents
      summary: Request Large Export Email
      description: 'Enqueue a large-export job — runs in the background and emails a

        secure, time-limited download link when the export finishes. 24h SLA

        promised in the email.'
      operationId: request_large_export_email
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LargeExportEmailRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/documents/upload-base64:
    post:
      tags:
      - Documents
      summary: Upload .docx/PDF/HTML/MD/RTF as the active editable document with chunk-ID…
      description: 'Parses the file into structured HTML where every paragraph, heading, table, row, and cell has a unique chunk ID, enabling the AI to make targeted structural edits via chat ("remove row 3 of the pricing table" works). Tables, borders, shading, alternating row colors, fonts, and inline styling are preserved on edit and export. Also works for AI-generated content: if you''ve drafted an outline or partial document in your context, upload it here as the working doc, then use chat to fill in the rest. This is also the reliable way to REPLACE a session''s document with exact content you already hold — the upload is a verbatim load, so it can never come back paraphrased or placeholder-shaped the way asking chat to re-type it can. When you pass a session_id the response is compact by default (metadata only — pass return_html=true for the full parsed HTML); the document is loaded into the session and you edit it via chat. For files >100KB, prefer request_upload_url (pre-signed URL flow) to avoid token bloat from base64 through the agent context. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives). Max 50 MB validated; note the hosted transport layer caps any REQUEST BODY at ~32 MB and rejects larger ones at the gateway with an HTML (not JSON) error — base64 inflates content ~33%, so inline uploads are reliable up to ~20 MB of file bytes; beyond that use request_upload_url (pre-signed flow, up to 100 MB).'
      operationId: upload_document_base64
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Base64UploadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_upload_document_to_editor:
      properties:
        file:
          type: string
          format: binary
          title: File
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        open_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Open Mode
          default: replace
      type: object
      required:
      - file
      title: Body_upload_document_to_editor
    Body_upload_inline_image:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_upload_inline_image
    Base64UploadRequest:
      properties:
        filename:
          type: string
          maxLength: 512
          title: Filename
          description: Original filename with extension (e.g. 'contract.pdf'). Used for file type detection.
        file_base64:
          type: string
          maxLength: 50000000
          title: File Base64
          description: Base64-encoded file content.
        session_id:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Session Id
          description: Session ID. Auto-generated if not provided.
        return_html:
          type: boolean
          title: Return Html
          description: 'With a session_id: false (default) returns compact metadata only (chunks_count, version_id, page_setup) — the document is loaded into the session and you edit it via chat, keeping your context small; true returns the full parsed HTML inline. Ignored on the convert-only path (no session_id), which always returns the converted html.'
          default: false
      type: object
      required:
      - filename
      - file_base64
      title: Base64UploadRequest
      description: JSON request body for base64-encoded file uploads.
    LargeExportEmailRequest:
      properties:
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        format:
          type: string
          title: Format
          default: docx
        options:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Options
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
        source_filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Filename
        recipient_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Recipient Email
      type: object
      title: LargeExportEmailRequest
      description: 'Body for POST /v1/documents/export/email-request.


        Used when a synchronous export exceeds the inline body cap. Send the same

        payload you would POST to /v1/documents/export (minus the html field —

        that comes from the session). The export is generated in the background

        and a secure download link is emailed within 24h.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer