API

TellusR API Overview

This documentation provides an overview of the TellusR API, which is divided into two sections:

  • General Operations Includes endpoints for managing projects, posting and retrieving data, and querying documents.
  • Admin Operations: Contains endpoints that require administrator privileges, such as managing semantic indexing. For detailed documentation on each API operation, please refer to the interactive OpenAPI docs.

Accessing API Documentation

Once the TellusR service is running (./tellusr.sh up), the API documentation will be available at: http://127.0.0.1:8900/docs

API

Ensure that these docs are accessible to developers who require them.

Authentication Requirement

The API requires authentication out of the box. Refer to tellusr.sh for instructions on how to register API users and manage access.

Project

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.

Adding documents

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.

Query

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.

Using the API to create semantic indexes

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.

Content index

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.

Title index

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.