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.


Decide on a project name for your documents. Documents passed to tellusr are stored in a project. 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 Semantic Search 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 files be sent using the /tellusr/api/v1/{project}/upload-many-files /tellusr/api/v1/{project}/upload-file APIs.

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.