This documentation page serves as background for the API.

Please refer to the interactive openapi docs for detailed documentation on each operation. After doing ./tellusr.sh up these docs should be available on:

Make sure to expose these docs to the developers that require them.


Documents passed to tellusr are stored in a project. Instructions on how to create such a project is described in the installation section. You can have multiple projects, but the documents passed to one project are not searchable from another project. From the APIs point of view a project acts as an ID for a collection of indexed documents, and two projects are always disjoint.

Each project is implemented by one or multiple solr collections; there is one main collection for keyword search with the same name as that of the project, and one collection for each semantic index the project owns. The semantic index collections follow the naming pattern {project}_{tag}. See the section on the Semantic Search Widget on how to generate a semantic index from the dashboard.

Adding documents

You can upload pdf/word-files directly using the

POST /tellusr/api/v1/{project}/upload-files

operation. By default, tellusr will structure the files in semantically relevant chunks.

We recommend that all pdf/word/html files be sent using the /tellusr/api/v1/{project}/upload-file /tellusr/api/v1/{project}/upload-file-background APIs. The upload-file variant returns a confirmation on successful uploads and is generally slower, if not invoked in parallel; the upload-file-background only returns a confirmation that the file has been accepted for processing and returns immediately - so it will be faster when invoked in serial.

IDs for files are autogenerated based on the filepath, but you can optionally embed existing IDs when making the API calls.

If your documents are already structured you can still post them using the

POST /tellusr/api/v1/{project}/update-doc
POST /tellusr/api/v1/{project}/update-many-docs



After posting documents you can make queries using the

GET  /tellusr/api/v1/{project}/query
POST /tellusr/api/v1/{project}/query

endpoints. See the openapi docs for documentation on parameters.