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.
Out of the box the API requires authentications. See tellusr.sh on how to register API users.
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.
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
operations.
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.