superdocs-app Attachments API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Attachments 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: Attachments
paths:
  /v1/attachments/upload:
    post:
      tags:
      - Attachments
      summary: Upload Attachment
      description: 'Upload a document attachment to a session for AI reference.


        The file is processed asynchronously — text is extracted, converted, and indexed

        so the AI can search and reference it during chat. Use GET /v1/attachments/status/{session_id}

        to check processing progress.


        Supported file types: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives) (max 50 MB).

        Returns a job_id for tracking the processing status.'
      operationId: upload_attachment
      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_attachment'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/attachments/{attachment_id}:
    delete:
      tags:
      - Attachments
      summary: Remove an attachment from a session or cancel its in-progress processing
      description: Removes the attachment from the session; the AI will no longer reference it in subsequent chat turns. If processing is still in progress, also cancels the underlying job. Use to free up context, remove sensitive files mid-session, or replace a stale reference document. The attachment_id can be either the final attachment ID or the job ID (during processing).
      operationId: delete_attachment
      security:
      - HTTPBearer: []
      parameters:
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
          title: Attachment Id
      - name: session_id
        in: query
        required: true
        schema:
          type: string
          title: Session Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/attachments/status/{session_id}:
    get:
      tags:
      - Attachments
      summary: Check processing status of all attachments in a session
      description: Returns each attachment's processing state (pending/processing/completed/failed) plus extracted text length and chunk count once ready. Poll this after upload_attachment_base64 to know when an attachment becomes queryable by the AI. Surfaces processing errors with actionable messages.
      operationId: get_attachment_status
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/attachments/upload-base64:
    post:
      tags:
      - Attachments
      summary: Upload a reference file (PDF/DOCX/image) for the AI to query while editing
      description: 'Files are processed asynchronously and become AI-searchable once ready. The AI can then reference the attachment''s content during chat (e.g., "rewrite section 3 to match the style guide PDF I attached"). Images are queryable via multimodal vision. Poll get_attachment_status to know when ready. Distinct from upload_document_base64: attachments are read-only context for the AI to reference, not the editable working document. 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). Requires session_id.'
      operationId: upload_attachment_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:
    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.
    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_attachment:
      properties:
        session_id:
          type: string
          title: Session Id
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - session_id
      - file
      title: Body_upload_attachment
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer