Upload a file

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")

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

Header Parameters

authorization?string|null

x-api-key?string|null

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

file*File

The file to upload (binary data)

workspace_id*Workspace Id

Workspace where the document will be stored.

filename?|

Custom filename (defaults to uploaded filename if not provided)

title?|

Custom title for the document. If not provided, defaults to filename without extension.

parser?|

Ingestion pipeline version to use. Defaults to "v1" (current platform pipeline).

tags?|

List of tag IDs to assign to the document on creation. Send as a JSON array string (e.g. '[1,2]') or as multiple form fields with the same name.

external_metadata?|

External source metadata for documents ingested from third-party systems. Provide as a JSON string with external_id (required), doc_type (optional), and additional_metadata (optional JSON object).

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/files" \  -F file="string" \  -F workspace_id="0"

{  "id": 0,  "filename": "string",  "workspace": {    "id": 0,    "name": "string",    "workspace_type": "string"  },  "summaries": [    {      "language": "en",      "summary": "string"    }  ],  "title": "string",  "extension": "string",  "status": "pending",  "status_vision": "pending",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "total_pages": 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",  "external_metadata": {    "external_id": "string",    "doc_type": "string",    "additional_metadata": null  },  "message": "string"}

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

207application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`