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
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. 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 documentation on 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.