List files accessible to the authenticated user
List files accessible to the authenticated user.
Authorization
bearerAuth 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
Header Parameters
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"`)