Files

List files accessible to the authenticated user

GET
/api/v1/files

List files accessible to the authenticated user.

Authorization

bearerAuth
AuthorizationBearer <token>

Console session token (Authorization: Bearer <session>) or product API key (Authorization: Bearer <api-key> or x-api-key). Session tokens are validated via Better Auth get-session; API keys against the shared database.

In: header

Query Parameters

created_at_after?string|null
created_at_before?string|null
extension?string|null
external_metadata__doc_type?string|null
external_metadata__external_id?string|null
filename?string|null
group_id?string|null
include_details?boolean|null
max_documents?integer|null
ordering?string|null
owner_id?string|null
page?integer|null
page_size?integer|null
search?string|null
search_details?boolean|null
search_details_chunks_limit?integer|null
status?string|null
status_vision?string|null
tag_id?string|null
title?string|null
total_pages_max?integer|null
total_pages_min?integer|null
updated_at_after?string|null
updated_at_before?string|null
upload_session_uuid?string|null
workspace_id?string|null

Header Parameters

authorization?string|null
x-api-key?string|null

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/files"
{  "count": 123,  "next": "http://api.example.org/accounts/?page=4",  "previous": "http://api.example.org/accounts/?page=2",  "results": [    {      "id": 0,      "filename": "string",      "workspace": {        "id": 0,        "name": "string",        "workspace_type": "string"      },      "summaries": [        {          "language": "en",          "summary": "string"        }      ],      "title": "string",      "extension": "string",      "status": "pending",      "status_detail": "string",      "status_vision": "pending",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "total_pages": 0,      "size": 0,      "tags": [        {          "id": 0,          "name": "string",          "auto_assigned": true        }      ],      "created_by": {        "id": 0,        "first_name": "string",        "last_name": "string",        "username": "string"      },      "upload_session_uuid": "77d43759-6ed9-4819-a910-9d5d508d4a5c",      "search_details": {        "relevant_chunks": [          {            "text": "string",            "chunk_type": "string",            "score": 0,            "scores": {              "text": 0,              "vision": 0,              "keyword": 0,              "multivector": 0,              "relevance": 0            }          }        ]      },      "signature": "string",      "parser": "string",      "external_metadata": {        "external_id": "string",        "doc_type": "string",        "additional_metadata": null      }    }  ]}

Search document chunks POST

Search document chunks Embedding → vector search → optional relevance scoring, returning ranked chunks with provenance. No LLM generation is performed. Billing: 1 retrieval credit per request. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id` (422). A 403 is returned when filters resolve to no authorized resources. When no filters are provided, search runs across all documents authorized for the API key. **Modes:** - `text` (default): hybrid text search - `vision`: VLM-embedded page image search **Images:** set `include_image=true` to receive a base64-encoded page image with each result. In text mode the image is fetched from the VisionChunk covering the chunk's start page (empty string if no vision index exists for that page). **Bounding boxes (PDF only):** set `include_bboxes=true` to append a `bboxes` array to each result, giving the merged rectangles of the chunk's text on the source PDF (raw PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating the chunk. One rectangle per logical group; a chunk spanning two pages produces at least one rectangle per page. Available for PDF documents in text mode only — returns an empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When `include_bboxes=false` (default) the `bboxes` key is omitted.

Upload a file POST

Upload a file to a workspace. Files are added to an upload session and queued for asynchronous processing. To track progress, retrieve the file details using the GET endpoints to check the current status. **Idempotent upload:** When `external_metadata.external_id` is provided and a manually-uploaded document with the same external ID already exists in the target workspace, the existing document is returned with `200 OK` instead of creating a duplicate. This makes bulk re-runs safe without requiring a pre-check. Datasource-imported documents are not affected. **Accepted file formats:** `csv`, `doc`, `docx`, `htm`, `html`, `jpeg`, `jpg`, `md`, `odp`, `odt`, `pdf`, `png`, `ppt`, `pptx`, `txt`, `xhtml`, `xls`, `xlsx` **Customization Options:** - `title`: Customize the document title (defaults to filename without extension) - `filename`: Override the uploaded filename - `parser`: Ingestion pipeline version (defaults to `"v1"`)