dialogbrain-com Files API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Files API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Files
paths:
  /api/files/upload-url:
    post:
      tags:
      - Files
      summary: Create Upload Url
      description: Start a direct-to-storage upload. PUT the bytes, then POST /complete.
      operationId: create_upload_url_api_files_upload_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/complete:
    post:
      tags:
      - Files
      summary: Complete Upload
      description: Confirm a direct upload landed and start processing.
      operationId: complete_upload_api_files__file_id__complete_post
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files:
    post:
      tags:
      - Files
      summary: Create File
      description: 'Upload binary blob or register remote URL for ingestion.


        Uses workspace-aware database and storage routing.'
      operationId: create_file_api_files_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_file_api_files_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Files
      summary: List Files
      description: 'Return paginated files for workspace.


        When `search` is provided AND `offset == 0`, additionally fans out a

        vector-image search via the RAG service and appends image-MIME hits

        that the filename ILIKE didn''t already match. This way a user typing

        "watercolor cat" finds the cat photo even when the filename is a

        Voyage UUID.'
      operationId: list_files_api_files_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Pagination offset
          default: 0
          title: Offset
        description: Pagination offset
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by status
          title: Status
        description: Filter by status
      - name: thread_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Restrict to thread
          title: Thread Id
        description: Restrict to thread
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by filename, title, or visual content (image vector search)
          title: Search
        description: Search by filename, title, or visual content (image vector search)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/search/content:
    get:
      tags:
      - Files
      summary: Search Files By Content
      description: 'Semantic search over file *contents* (not filenames).


        Embeds the query, vector-searches the workspace''s RAG chunks via the RAG

        orchestrator, then collapses chunk hits down to their source files —

        keeping the best score + snippet per file — and returns full file records

        ranked by relevance. This is the content-search counterpart to the

        filename ILIKE search in `list_files`.


        Degrades gracefully: a RAG outage yields an empty result set, never a 500.'
      operationId: search_files_by_content_api_files_search_content_get
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          description: Semantic content query
          title: Query
        description: Semantic content query
      - name: threshold
        in: query
        required: false
        schema:
          type: number
          maximum: 1.0
          minimum: 0.0
          description: Min similarity score
          default: 0.4
          title: Threshold
        description: Min similarity score
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max distinct files to return
          default: 50
          title: Limit
        description: Max distinct files to return
      - name: file_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Restrict to a type bucket: presentation | document | image'
          title: File Type
        description: 'Restrict to a type bucket: presentation | document | image'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileContentSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}:
    get:
      tags:
      - Files
      summary: Fetch File
      description: Get a single file with all versions.
      operationId: fetch_file_api_files__file_id__get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Files
      summary: Delete File
      description: 'Hard-delete a file: wipe storage blobs for all versions, then cascade

        DELETEs across file_versions / file_pages / file_processing_jobs /

        file_sends / rag_chunks / files. Workspace-scoped — cross-workspace

        requests 404.


        Mirrors the per-file cleanup the channel-disconnect handler does at

        `channels/accounts.py:660-885` so the two paths stay consistent.

        Used by the new /files workspace UI to let operators clean up

        orphaned screenshots, browser-mcp uploads, voice-clone reference

        clips, and other unbound files that the channel-disconnect cleanup

        skips (it only touches files bound to threads of the disconnected

        channel).'
      operationId: delete_file_api_files__file_id__delete
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/access-token:
    post:
      tags:
      - Files
      summary: Create File Access Token
      description: 'Generate a short-lived opaque token scoped to a single file.


        Returns a token valid for 5 minutes that can be used as ?file_token=

        in URLs opened in new browser tabs (where Authorization header isn''t available).'
      operationId: create_file_access_token_api_files__file_id__access_token_post
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/download:
    get:
      tags:
      - Files
      summary: Download File
      description: 'Download the latest version of a file.


        By default, redirects to a presigned URL for direct download from storage (fast).

        Use ?direct=true to download through the API gateway (slower, for debugging).

        Use ?url_only=true to get the presigned URL as JSON (for CORS-safe frontend fetching).'
      operationId: download_file_api_files__file_id__download_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      - name: direct
        in: query
        required: false
        schema:
          type: boolean
          description: If true, download through gateway instead of redirect
          default: false
          title: Direct
        description: If true, download through gateway instead of redirect
      - name: url_only
        in: query
        required: false
        schema:
          type: boolean
          description: If true, return presigned URL as JSON instead of redirect
          default: false
          title: Url Only
        description: If true, return presigned URL as JSON instead of redirect
      - name: attachment
        in: query
        required: false
        schema:
          type: boolean
          description: If true, the presigned URL answers as a file to save, not one to show
          default: false
          title: Attachment
        description: If true, the presigned URL answers as a file to save, not one to show
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/avatar:
    get:
      tags:
      - Files
      summary: Avatar Preview
      description: 'Public endpoint for avatar images (no auth required).


        Downloads from S3 and streams directly with cache headers.

        Cached at 3 layers: browser (7d) → nginx proxy_cache (7d) → in-memory dict → S3.


        Unauthenticated because the URL is rendered in an ``, which cannot

        carry the Bearer header. That makes the reference check below the ONLY thing

        standing between a stranger and the file: serve a file id ONLY when some row

        actually points at it as its avatar. Without that check "is it an image?"

        was the whole gate, so walking the id space returned every chat photo,

        screenshot and post thumbnail of every workspace — 16398 images against 7

        real avatars when this was measured.'
      operationId: avatar_preview_api_files__file_id__avatar_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/preview:
    get:
      tags:
      - Files
      summary: Preview File
      description: 'Preview a file inline in the browser (for images, PDFs, etc.)


        By default, redirects to a presigned URL for direct access from storage (fast).

        Use ?direct=true to stream through the API gateway (slower).


        For non-previewable file types, falls back to download behavior.'
      operationId: preview_file_api_files__file_id__preview_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      - name: direct
        in: query
        required: false
        schema:
          type: boolean
          description: If true, download through gateway instead of redirect
          default: false
          title: Direct
        description: If true, download through gateway instead of redirect
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/preview-pdf:
    get:
      tags:
      - Files
      summary: Preview Office As Pdf
      description: 'Convert an Office file (PPTX/DOCX/XLSX/...) to PDF on demand for in-app preview.


        The frontend FileViewer modal renders PDF in an iframe, but browsers can''t

        render Office Open XML formats natively. This endpoint shells out to

        LibreOffice headless on the api-gateway pod, caches the converted PDF

        per file_version, and streams it back so the same modal works for all

        document types.


        PDFs already pass through `/preview` unchanged — the frontend should only

        hit this route when the source mime_type is in SUPPORTED_OFFICE_MIMES.'
      operationId: preview_office_as_pdf_api_files__file_id__preview_pdf_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/progress:
    get:
      tags:
      - Files
      summary: Get File Progress
      description: 'Get file processing progress including chunk count.


        Returns the current processing stage, chunk count, and overall progress.

        Useful for showing upload/processing status in UI.'
      operationId: get_file_progress_api_files__file_id__progress_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileProgressResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/files/{file_id}/process:
    post:
      tags:
      - Files
      summary: Trigger Processing
      description: Trigger downstream processing stage for a file.
      operationId: trigger_processing_api_files__file_id__process_post
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
          title: File Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessFileRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateUploadUrlRequest:
      properties:
        filename:
          type: string
          title: Filename
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
        size_bytes:
          type: integer
          exclusiveMinimum: 0.0
          title: Size Bytes
          description: Exact byte length of the file
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
          description: Hex sha256; enables dedup + verification
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - filename
      - size_bytes
      title: CreateUploadUrlRequest
    FileContentSearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/FileContentMatch'
          type: array
          title: Results
        total:
          type: integer
          title: Total
          description: Number of distinct files matched
          default: 0
      type: object
      required:
      - results
      title: FileContentSearchResponse
      description: Result wrapper for semantic file-content search.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FileResponse:
      properties:
        id:
          type: integer
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        status:
          type: string
          title: Status
        ingest_type:
          type: string
          title: Ingest Type
        latest_version:
          type: integer
          title: Latest Version
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
        byte_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Byte Size
        original_filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Original Filename
        thread_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thread Id
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        versions:
          items:
            $ref: '#/components/schemas/FileVersionResponse'
          type: array
          title: Versions
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
        chunk_count:
          type: integer
          title: Chunk Count
          description: Number of RAG chunks for this file
          default: 0
      type: object
      required:
      - id
      - status
      - ingest_type
      - latest_version
      - created_at
      - updated_at
      title: FileResponse
      description: File resource returned to clients.
    FileVersionResponse:
      properties:
        id:
          type: integer
          title: Id
        file_id:
          type: integer
          title: File Id
        version_number:
          type: integer
          title: Version Number
        storage_bucket:
          type: string
          title: Storage Bucket
        storage_key:
          type: string
          title: Storage Key
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
        byte_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Byte Size
        checksum_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Checksum Sha256
        created_at:
          type: string
          format: date-time
          title: Created At
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
      type: object
      required:
      - id
      - file_id
      - version_number
      - storage_bucket
      - storage_key
      - created_at
      title: FileVersionResponse
      description: Single file version metadata.
    FileContentMatch:
      properties:
        id:
          type: integer
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        status:
          type: string
          title: Status
        ingest_type:
          type: string
          title: Ingest Type
        latest_version:
          type: integer
          title: Latest Version
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
        byte_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Byte Size
        original_filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Original Filename
        thread_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thread Id
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        versions:
          items:
            $ref: '#/components/schemas/FileVersionResponse'
          type: array
          title: Versions
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
        chunk_count:
          type: integer
          title: Chunk Count
          description: Number of RAG chunks for this file
          default: 0
        relevance:
          type: number
          title: Relevance
          description: Best chunk similarity score 0.0-1.0
          default: 0.0
        snippet:
          anyOf:
          - type: string
          - type: 'null'
          title: Snippet
          description: Best matching text excerpt
      type: object
      required:
      - id
      - status
      - ingest_type
      - latest_version
      - created_at
      - updated_at
      title: FileContentMatch
      description: 'A file surfaced by semantic content search.


        Extends the plain file record with the best similarity score and the

        matching text snippet so the UI can rank + preview why it matched.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FileProgressResponse:
      properties:
        file_id:
          type: integer
          title: File Id
        status:
          type: string
          title: Status
        chunk_count:
          type: integer
          title: Chunk Count
          default: 0
        current_stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Stage
        progress:
          additionalProperties:
            type: integer
          type: object
          title: Progress
      type: object
      required:
      - file_id
      - status
      title: FileProgressResponse
      description: File processing progress response.
    FileListResponse:
      properties:
        files:
          items:
            $ref: '#/components/schemas/FileResponse'
          type: array
          title: Files
        total:
          type: integer
          title: Total
          description: Total number of files matching filters
          default: 0
        offset:
          type: integer
          title: Offset
          description: Current offset
          default: 0
        limit:
          type: integer
          title: Limit
          description: Requested limit
          default: 20
        has_more:
          type: boolean
          title: Has More
          description: Whether more files are available
          default: false
      type: object
      required:
      - files
      title: FileListResponse
      description: List wrapper with pagination info.
    Body_create_file_api_files_post:
      properties:
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        thread_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thread Id
      type: object
      title: Body_create_file_api_files_post
    ProcessFileRequest:
      properties:
        stage:
          type: string
          title: Stage
          description: Stage to enqueue
          default: extract
          examples:
          - extract
          - chunking
          - embedding
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      title: ProcessFileRequest
      description: Manual processing trigger request.