dialogbrain-com Files API
The files API from dialogbrain-com — 12 operation(s) for files.
The files API from dialogbrain-com — 12 operation(s) for files.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/dialogbrain-com:dialogbrain-com-files-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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.