superdocs-app Uploads API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Uploads 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: Uploads
paths:
  /v1/uploads:
    post:
      tags:
      - Uploads
      summary: Get a pre-signed URL to upload large files (.docx/PDF/HTML/MD/RTF) without…
      description: 'Returns a short-lived (5-minute) PUT URL plus a ready-to-run `curl_example`. An agent with shell access can run the `curl_example` directly to push the file to cloud storage, so the bytes never pass through its context window; clients without shell execution can surface the command or URL for the caller to run. After upload completes, call process_uploaded_document with the upload_id to trigger parsing. For files <100KB where token cost is trivial, upload_document_base64 still works inline. Max file size: 100 MB. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives).'
      operationId: request_upload_url
      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/UploadUrlRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadUrlResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/uploads/{upload_id}/process:
    post:
      tags:
      - Uploads
      summary: Parse an uploaded file into structured HTML with chunk IDs for targeted AI…
      description: 'Fetches the file uploaded via request_upload_url and runs the same parsing pipeline as upload_document_base64: every paragraph, heading, table, row, and cell gets a unique chunk ID, enabling targeted structural edits via chat ("remove row 3 of the pricing table" works), with tables, borders, shading, alternating row colors, fonts, and inline styling preserved on edit and export. By default the response is compact (metadata only, no document body) to keep your context small — the document is loaded into the session and you edit it via chat; pass return_html=true if you need the parsed HTML inline. Uploading and parsing is NOT itself a billable operation — you are charged only when the AI edits the document. Specify parse_mode=''document'' to load as the active editable document, or parse_mode=''attachment'' to load as a read-only AI-searchable reference.'
      operationId: process_uploaded_document
      security:
      - HTTPBearer: []
      parameters:
      - name: upload_id
        in: path
        required: true
        schema:
          type: string
          description: The upload_id returned by request_upload_url.
          title: Upload Id
        description: The upload_id returned by request_upload_url.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessUploadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessDocumentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/downloads:
    post:
      tags:
      - Uploads
      summary: Get a pre-signed URL to download an exported document without proxying through…
      description: Returns a short-lived (15-minute) GET URL plus a ready-to-run `curl_example`. An agent with shell access can run the `curl_example` directly to save the exported file to the working directory, so the bytes never pass through its context window; clients without shell execution (or callers who only want the link) can use the signed URL directly. Generates the document in the requested format and returns a time-limited signed download URL. Specify format as 'pdf', 'docx', 'html', 'markdown', or 'txt' (legacy 'doc' also accepted).
      operationId: request_download_url
      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/DownloadUrlRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadUrlResponse'
        '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
    ProcessUploadRequest:
      properties:
        session_id:
          type: string
          maxLength: 256
          pattern: ^[a-zA-Z0-9_\-\.]+$
          title: Session Id
          description: Session ID to load this document/attachment into. Must match the chat/async session-id format — letters, digits, '_', '-', '.' only (no ':'); max 256 chars.
        filename:
          type: string
          maxLength: 255
          title: Filename
          description: Same filename passed to request_upload_url.
        parse_mode:
          type: string
          enum:
          - document
          - attachment
          title: Parse Mode
          description: '''document'' = parse and load as the active editable doc; ''attachment'' = process asynchronously as AI-searchable reference (returns job_id to poll).'
          default: document
        return_html:
          type: boolean
          title: Return Html
          description: When false (default), the response is compact — metadata only (chunks_count, version_id, page_setup), no document body — to keep your context small; the document is loaded into the session and you edit it via chat. Set true only if you actually need the parsed HTML returned inline.
          default: false
        open_mode:
          type: string
          enum:
          - replace
          - new_tab
          - new_focused
          - background
          title: Open Mode
          description: 'parse_mode=''document'' only. ''replace'' (default): the document replaces the session''s focused document. ''new_tab'' / ''new_focused'': it opens as an additional document and becomes the focused one. ''background'': it opens as an additional document without changing which document is focused.'
          default: replace
      type: object
      required:
      - session_id
      - filename
      title: ProcessUploadRequest
    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
    DownloadUrlRequest:
      properties:
        session_id:
          type: string
          maxLength: 256
          title: Session Id
          description: Session ID whose current document should be exported and packaged for download.
        format:
          type: string
          enum:
          - docx
          - pdf
          - html
          - markdown
          - txt
          - doc
          title: Format
          description: Export format (docx, pdf, html, markdown, txt).
          default: docx
        filename:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Filename
          description: Optional Content-Disposition filename for the download (without extension). Auto-detected from the document's first heading if not provided.
        options:
          $ref: '#/components/schemas/ExportOptions'
          description: Customization (paper, margins, filename, watermark, etc.). Mirrors ExportRequest.options.
      type: object
      required:
      - session_id
      title: DownloadUrlRequest
    UploadUrlRequest:
      properties:
        filename:
          type: string
          maxLength: 255
          title: Filename
          description: Original filename including extension (e.g. 'contract.docx'). Used downstream for file-type detection.
        content_type:
          type: string
          maxLength: 200
          title: Content Type
          description: MIME type the agent will PUT with (e.g. 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' for .docx).
        size_bytes:
          type: integer
          maximum: 104857600.0
          exclusiveMinimum: 0.0
          title: Size Bytes
          description: File size in bytes. Must be > 0 and <= 104857600 (100 MB).
        purpose:
          type: string
          enum:
          - document
          - attachment
          - export-html
          title: Purpose
          description: What this file will be used for. 'document' = the active editable doc; 'attachment' = read-only AI-searchable reference; 'export-html' = HTML payload destined for /v1/documents/export (large-export upload flow, for documents above ~25 MB).
          default: document
      type: object
      required:
      - filename
      - content_type
      - size_bytes
      title: UploadUrlRequest
    DownloadUrlResponse:
      properties:
        download_url:
          type: string
          title: Download Url
        expires_at:
          type: string
          title: Expires At
        expires_in_seconds:
          type: integer
          title: Expires In Seconds
        curl_example:
          type: string
          title: Curl Example
        filename:
          type: string
          title: Filename
        format:
          type: string
          title: Format
      type: object
      required:
      - download_url
      - expires_at
      - expires_in_seconds
      - curl_example
      - filename
      - format
      title: DownloadUrlResponse
    ProcessDocumentResponse:
      properties:
        document_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Document Id
          description: 'parse_mode=''document'': the id of the open document the file was loaded as (use it with document_id on chat, focus and close).'
        html:
          anyOf:
          - type: string
          - type: 'null'
          title: Html
        session_id:
          type: string
          title: Session Id
        filename:
          type: string
          title: Filename
        chunks_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chunks Count
        version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Version Id
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
        status:
          type: string
          title: Status
        parse_mode:
          type: string
          title: Parse Mode
        page_setup:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Page Setup
        warnings:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Warnings
      type: object
      required:
      - session_id
      - filename
      - status
      - parse_mode
      title: ProcessDocumentResponse
    UploadUrlResponse:
      properties:
        upload_id:
          type: string
          title: Upload Id
        upload_url:
          type: string
          title: Upload Url
        expires_at:
          type: string
          title: Expires At
        expires_in_seconds:
          type: integer
          title: Expires In Seconds
        max_size_bytes:
          type: integer
          title: Max Size Bytes
        curl_example:
          type: string
          title: Curl Example
      type: object
      required:
      - upload_id
      - upload_url
      - expires_at
      - expires_in_seconds
      - max_size_bytes
      - curl_example
      title: UploadUrlResponse
    ExportOptions:
      properties:
        paper_size:
          type: string
          enum:
          - A4
          - Letter
          - A3
          - Legal
          title: Paper Size
          description: Page size for DOCX/PDF/legacy .doc. HTML/MD/TXT exports ignore.
          default: Letter
        orientation:
          type: string
          enum:
          - portrait
          - landscape
          title: Orientation
          description: Page orientation for DOCX/PDF/legacy .doc.
          default: portrait
        margins:
          type: string
          enum:
          - narrow
          - normal
          - wide
          - custom
          title: Margins
          description: Page margins preset. 'narrow' = 0.5in, 'normal' = 1.0in, 'wide' = 1.5in. 'custom' uses custom_margins_inches.
          default: normal
        custom_margins_inches:
          anyOf:
          - additionalProperties:
              type: number
            propertyNames:
              enum:
              - top
              - right
              - bottom
              - left
            type: object
          - type: 'null'
          title: Custom Margins Inches
          description: Required when margins='custom'. Each value 0.25-3.0 inches.
        filename:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Filename
          description: Custom filename (no extension). Auto-detected from first <h1> if unset.
        embed_images:
          type: boolean
          title: Embed Images
          description: HTML export only. When True, images are base64-embedded for offline portability (raises size cap to 150 MB). When False, images are referenced by URL (smaller file, online-only).
          default: false
        watermark_text:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Watermark Text
          description: PDF only. Optional text watermark overlaid on every page.
        watermark_opacity:
          type: number
          maximum: 1.0
          minimum: 0.05
          title: Watermark Opacity
          description: PDF watermark opacity, 0.05-1.0.
          default: 0.3
        fidelity:
          anyOf:
          - type: string
            enum:
            - strict
            - compat
          - type: 'null'
          title: Fidelity
          description: Export fidelity. 'strict' (server default) renders only the formatting the document carries — no imposed table widths/borders (except visual defaults on fully unstyled tables), overflow-only clamping, highlight colors honored. 'compat' reproduces the legacy normalized output.
      type: object
      title: ExportOptions
      description: 'User-facing export customisation (page size, orientation, margins,

        filename, watermark). Sent on every export request.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer