This documentation provides an overview of the TellusR API, which is divided into two sections:
Once the TellusR service is running (./tellusr.sh up), the API documentation will be available at: http://127.0.0.1:8900/docs
Ensure that these docs are accessible to developers who require them.
The API requires authentication out of the box. Refer to tellusr.sh for instructions on how to register API users and manage access.
Documents passed to tellusr are stored in a project. See the API on how to add projects. 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.
See the documentation further down on how to add a semantic index using our API, or the Semantic Search 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-file-background
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.
You can use the following API endpoint to add semantic indexes:
POST /tellusr/admin/api/v1/{project}/semantic-index
We recommend adding two semantic indexes for each project, one for the content of your documents, and one for the titles of your documents.
The content index should be based on the content of your documents. When uploading files with the file upload operations, the content will be stored in a chunked format under content_segmented
. To target these chunks use the following index configuration:
{
"language": "MULTILINGUAL",
"fields": ["content_segment"]
}
Select language according to needs.
When configuring the title index, it is recommended to set the minWords parameter to 1, as titles are typically quite short. By default, minWords is set to 10, which means that any title containing fewer than 10 words will not be indexed.
{
"language": "MULTILINGUAL",
"fields": ["title"],
"minWords": 1
}
Select language according to needs. See API documentation for details.