Github

Community

Blog

Trieve

API Reference

Support

Dashboard

This is the callback route for the OAuth provider, it should not be called directly. Redirects to browser with set-cookie header.

OpenID Connect callback

Trieve is an API for building search, recommendations, and RAG experiences.

Introduction

Quickly start building search, recommendations, and RAG for your application with Trieve

Quickstart

Basic terms and concepts used commonly within the Trieve ecosystem.

Trieve Primitives

Screenshots of Trieve in action across various use cases.

Screenshots

Learn how to self-host Trieve with Docker Compose

Docker Compose Setup

Learn how to self-host Trieve on local Kubernetes

Local Kubernetes Setup

AWS Self Hosting

Learn how to self-host Trieve on Google Cloud Platform

GCP Self Hosting

Learn how to upload your chunks to Trieve

Uploading Chunks to Trieve

Uploading Files to Trieve

Learn how to search over your data with Trieve

Searching with Trieve

Learn how to recommend content with Trieve

Recommending with Trieve

Learn how to chat with your data with Trieve

RAG with Trieve

Learn how to build a job board with Trieve

Build Search for a Job Board

Build Search for Ecommerce

Create new chunk(s). If the chunk has the same tracking_id as an existing chunk, the request will fail. Once a chunk is created, it can be searched for using the search endpoint.
If uploading in bulk, the maximum amount of chunks that can be uploaded at once is 120 chunks. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Create or Upsert Chunk or Chunks

This route provides the primary search functionality for the API. It can be used to search for chunks by semantic similarity, full-text similarity, or a combination of both. Results' `chunk_html` values will be modified with `<b><mark>` tags for sub-sentence highlighting.

Search

This route provides the primary autocomplete functionality for the API. This prioritize prefix matching with semantic or full-text search.

Autocomplete

Get recommendations of chunks similar to the positive samples in the request and dissimilar to the negative.

Get Recommended Chunks

This endpoint exists as an alternative to the topic+message resource pattern where our Trieve handles chat memory. With this endpoint, the user is responsible for providing the context window and the prompt and the conversation is ephemeral.

RAG on Specified Chunks

This endpoint will generate 3 suggested queries based off a hybrid search using RAG with the query provided in the request body and return them as a JSON object.

Generate suggested queries

This route can be used to determine the number of chunk results that match a search query including score threshold and filters. It may be high latency for large limits. There is a dataset configuration imposed restriction on the maximum limit value (default 10,000) which is used to prevent DDOS attacks. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Count chunks above threshold

Get paginated chunks from your dataset with filters and custom sorting. If sort by is not specified, the results will sort by the id's of the chunks in ascending order. Sort by and offset_chunk_id cannot be used together; if you want to scroll with a sort by then you need to use a must_not filter with the ids you have already seen. There is a limit of 1000 id's in a must_not filter at a time.

Scroll Chunks

Update a chunk. If you try to change the tracking_id of the chunk to have the same tracking_id as an existing chunk, the request will fail. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Update Chunk

Update a chunk by tracking_id. This is useful for when you are coordinating with an external system and want to use the tracking_id to identify the chunk. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Update Chunk By Tracking Id

Get a singular chunk by tracking_id. This is useful for when you are coordinating with an external system and want to use your own id as the primary reference for a chunk.

Get Chunk By Tracking Id

Delete a chunk by tracking_id. This is useful for when you are coordinating with an external system and want to use the tracking_id to identify the chunk. If deleting a root chunk which has a collision, the most recently created collision will become a new root chunk. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete Chunk By Tracking Id

Get Chunk By Id

Delete a chunk by its id. If deleting a root chunk which has a collision, the most recently created collision will become a new root chunk. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete Chunk

Get Chunks By Ids

Get Chunks By Tracking Ids

Create new chunk_group(s). This is a way to group chunks together. If you try to create a chunk_group with the same tracking_id as an existing chunk_group, this operation will fail. Only 1000 chunk groups can be created at a time. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Create or Upsert Group or Groups

This route allows you to get groups as results instead of chunks. Each group returned will have the matching chunks sorted by similarity within the group. This is useful for when you want to get groups of chunks which are similar to the search query. If choosing hybrid search, the results will be re-ranked using scores from a cross encoder model. Compatible with semantic, fulltext, or hybrid search modes.

Search Over Groups

This route allows you to search only within a group. This is useful for when you only want search results to contain chunks which are members of a specific group. If choosing hybrid search, the results will be re-ranked using scores from a cross encoder model.

Search Within Group

Route to get recommended groups. This route will return groups which are similar to the groups in the request body. You must provide at least one positive group id or group tracking id.

Get Recommended Groups

Update a chunk_group. One of group_id or tracking_id must be provided. If you try to change the tracking_id to one that already exists, this operation will fail. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Update Group

Update a chunk_group with the given tracking id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Update Group by Tracking ID

Route to add a chunk to a group. One of chunk_id or chunk_tracking_id must be provided. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Add Chunk to Group

Route to remove a chunk from a group. Auth'ed user or api key must be an admin or owner of the dataset's organization to remove a chunk from a group.

Remove Chunk from Group

Route to get the groups that a chunk is in.

Get Groups for Chunks

Route to get all chunks for a group. The response is paginated, with each page containing 10 chunks. Support for custom page size is coming soon. Page is 1-indexed.

Get Chunks in Group by Tracking ID

Fetch the group with the given tracking id.
get_group_by_tracking_id

Get Group by Tracking ID

Route to add a chunk to a group by tracking id. One of chunk_id or chunk_tracking_id must be provided. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Add Chunk to Group by Tracking ID

Delete a chunk_group with the given tracking id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete Group by Tracking ID

Fetch the group with the given id.
get_group

Get Group

This will delete a chunk_group. If you set delete_chunks to true, it will also delete the chunks within the group. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete Group

Route to get all chunks for a group. The response is paginated, with each page containing 10 chunks. Page is 1-indexed.

Get Chunks in Group

Fetch the groups which belong to a dataset specified by its id.

Get Groups for Dataset

Create a new chat topic. Topics are attached to a owner_id's and act as a coordinator for conversation message history of gen-AI chat sessions. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Create Topic

Update an existing chat topic. Currently, only the name of the topic can be updated. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Update Topic

Get all topics belonging to an arbitary owner_id. This is useful for managing message history and chat sessions. It is common to use a browser fingerprint or your user's id as the owner_id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Get All Topics for Owner ID

Delete an existing chat topic. When a topic is deleted, all associated chat messages are also deleted. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete Topic

Create message. Messages are attached to topics in order to coordinate memory of gen-AI chat sessions.Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Create message

Edit message which exists within the topic's chat history. This will delete the message and replace it with a new message. The new message will be generated by the AI based on the new content provided in the request body. The response will include Chunks first on the stream if the topic is using RAG. The structure will look like `[chunks]||mesage`. See docs.trieve.ai for more information. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Edit message

Regenerate the assistant response to the last user message of a topic. This will delete the last message and replace it with a new message. The response will include Chunks first on the stream if the topic is using RAG. The structure will look like `[chunks]||mesage`. See docs.trieve.ai for more information. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Regenerate message

Get all messages for a given topic. If the topic is a RAG topic then the response will include Chunks first on each message. The structure will look like `[chunks]||mesage`. See docs.trieve.ai for more information.

Get all messages for a given topic

Upload a file to S3 attached to the server. The file will be converted to HTML with tika and chunked algorithmically, images will be OCR'ed with tesseract. The resulting chunks will be indexed and searchable. Optionally, you can only upload the file and manually create chunks associated to the file after. See docs.trieve.ai and/or contact us for more details and tips. Auth'ed user must be an admin or owner of the dataset's organization to upload a file.

Upload File

Get all files which belong to a given dataset specified by the dataset_id parameter. 10 files are returned per page.

Get Files for Dataset

Get File

Delete a file from S3 attached to the server based on its id. This will disassociate chunks from the file, but only delete them all together if you specify delete_chunks to be true. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Delete File

This route allows you to send CTR data to the system.

Send CTR Data

This route allows you to view the CTR analytics for a dataset.

Get CTR Analytics

This route allows you to view the RAG analytics for a dataset.

Get RAG Analytics

This route allows you to view the search analytics for a dataset.

Get Search Analytics

This route allows you to view the cluster analytics for a dataset.

Get Cluster Analytics

This route allows you to view the top datasets for a given type.

Get Top Datasets

Rate Query

This route allows you to send event data to the system.

Send Event Data

Auth'ed user must be an owner of the organization to create a dataset.

Create Dataset

One of id or tracking_id must be provided. The auth'ed user must be an owner of the organization to update a dataset.

Update Dataset by ID or Tracking ID

Removes all chunks, files, and groups from the dataset while retaining the analytics and dataset itself. The auth'ed user must be an owner of the organization to clear a dataset.

Clear Dataset

Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Get Dataset By ID

Scroll through all tags in the dataset and get the number of chunks in the dataset with that tag plus the total number of unique tags for the whole datset.

Get All Tags

Get Datasets from Organization

Auth'ed user must be an owner of the organization to delete a dataset.

Delete Dataset by Tracking ID

Get Usage By Dataset ID

Delete Dataset

Get events for the dataset specified by the TR-Dataset header.

Get events for the dataset

Update the configurations for all datasets in an organization. Only the specified keys in the configuration object will be changed per dataset such that you can preserve dataset unique values. Auth'ed user or api key must have an owner role for the specified organization.

Update All Dataset Configurations

Create a new organization. The auth'ed user who creates the organization will be the default owner of the organization.

Create Organization

Update an organization. Only the owner of the organization can update it.

Update Organization

Delete an organization by its id. The auth'ed user must be an owner of the organization to delete it.

Delete Organization

Fetch the current usage specification of an organization by its id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Get Organization Usage

Fetch the details of an organization by its id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Get Organization

Fetch the users of an organization by its id. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Get Organization Users

Update a user's information. If the user_id is not provided, the auth'ed user will be updated. If the user_id is provided, the role of the auth'ed user or api key must be an admin (1) or owner (2) of the organization.

Update User

Create a new api key for the auth'ed user. Successful response will contain the newly created api key. If a write role is assigned the api key will have permission level of the auth'ed user who calls this endpoint.

Set User Api Key

Delete User Api Key

This will redirect you to the OAuth provider for authentication with email/pass, SSO, Google, Github, etc.

Login

Invalidate your current auth credential stored typically stored in a cookie. This does not invalidate your API key.

Logout

Get the user corresponding to your current auth credentials.

Get Me

Confirmation that the service is healthy and can make embedding vectors

Health Check

Invitations act as a way to invite users to join an organization. After a user is invited, they will automatically be added to the organization with the role specified in the invitation once they set their. Auth'ed user or api key must have an admin or owner role for the specified dataset's organization.

Send Invitation

Get All Invoices

Get a 303 SeeOther redirect link to the stripe checkout page for the plan and organization

Checkout

Get All Plans

Cancel Subscription

Update Subscription Plan

This route allows you to view the number of items in each queue in the Prometheus format.

Chunk

Chunk Group

Topic

Message

File

Analytics

Dataset

Events

Organization

User

Auth

Health

Invitation

Stripe

Metrics

OpenID Connect callback

Response