Files API: Upload, Get, Update, Delete

Overview

The file resource is the underlying object behind everything you upload for use with a Knowledge Base. This page is the API reference for creating, retrieving, updating, and deleting individual files. For how uploaded files get attached to an assistant's knowledge base — via the dashboard or the query-tool API — and for file-size and structuring best practices, see Knowledge Base.

Send a POST request to /file as multipart/form-data with the file itself:

curl --location 'https://api.sulus.ai/file' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--form 'file=@"<PATH_TO_YOUR_FILE>"'

Supported formats: .txt, .pdf, .docx, .doc, .csv, .md, .tsv, .yaml, .json, .xml, and .log. On success (201), the response is a File object (see the field table below). A 400 response is returned if the file is invalid.

Retrieve a file's details with a GET request to /file/{id}:

curl --request GET \
  --url https://api.sulus.ai/file/{id} \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Path parameter: id (string, required) — the unique identifier of the file.

Update a file's display name with a PATCH request to /file/{id}. Currently, only the display name can be changed through this endpoint — not the file's contents.

curl --request PATCH \
  --url https://api.sulus.ai/file/{id} \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"name": "new-file-name"}'

Delete a file with a DELETE request to /file/{id}. The response returns the deleted File object.

curl --request DELETE \
  --url https://api.sulus.ai/file/{id} \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Every endpoint above returns a File object with the following fields:

A file typically starts in processing status right after upload while text is extracted, and moves to done once it's ready to be referenced in a knowledge base — check status before relying on parsedTextUrl being populated.