> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trieve.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Edit message
> This will delete the specified message and replace it with a new message. All messages after the message being edited in the sort order will be deleted. 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.
## OpenAPI
````yaml put /api/message
openapi: 3.0.3
info:
title: Trieve API
description: >-
Trieve OpenAPI Specification. This document describes all of the operations
available through the Trieve API.
contact:
name: Trieve Team
url: https://trieve.ai
email: developers@trieve.ai
license:
name: BSL
url: https://github.com/devflowinc/trieve/blob/main/LICENSE.txt
version: 0.13.0
servers:
- url: https://api.trieve.ai
description: Production server
- url: http://localhost:8090
description: Local development server
security: []
tags:
- name: Invitation
description: Invitation endpoint. Exists to invite users to an organization.
- name: Auth
description: Authentication endpoint. Serves to register and authenticate users.
- name: User
description: User endpoint. Enables you to modify user roles and information.
- name: Organization
description: >-
Organization endpoint. Enables you to modify organization roles and
information.
- name: Dataset
description: >-
Dataset endpoint. Datasets belong to organizations and hold configuration
information for both client and server. Datasets contain chunks and chunk
groups.
- name: Chunk
description: >-
Chunk endpoint. Think of chunks as individual searchable units of
information. The majority of your integration will likely be with the
Chunk endpoint.
- name: Chunk Group
description: >-
Chunk groups endpoint. Think of a chunk_group as a bookmark folder within
the dataset.
- name: Crawl
description: Crawl endpoint. Used to create and manage crawls for datasets.
- name: File
description: >-
File endpoint. When files are uploaded, they are stored in S3 and broken
up into chunks with text extraction from Apache Tika. You can upload files
of pretty much any type up to 1GB in size. See chunking algorithm details
at `docs.trieve.ai` for more information on how chunking works. Improved
default chunking is on our roadmap.
- name: Events
description: >-
Notifications endpoint. Files are uploaded asynchronously and events are
sent to the user when the upload is complete.
- name: Topic
description: >-
Topic chat endpoint. Think of topics as the storage system for gen-ai chat
memory. Gen AI messages belong to topics.
- name: Message
description: >-
Message chat endpoint. Messages are units belonging to a topic in the
context of a chat with a LLM. There are system, user, and assistant
messages.
- name: Stripe
description: >-
Stripe endpoint. Used for the managed SaaS version of this app. Eventually
this will become a micro-service. Reach out to the team using contact info
found at `docs.trieve.ai` for more information.
- name: Health
description: Health check endpoint. Used to check if the server is up and running.
- name: Metrics
description: Metrics endpoint. Used to get information for monitoring
- name: Analytics
description: Analytics endpoint. Used to get information for search and RAG analytics
- name: Experiment
description: Experiment endpoint. Used to create and manage experiments
paths:
/api/message:
put:
tags:
- Message
summary: Edit message
description: >-
This will delete the specified message and replace it with a new
message. All messages after the message being edited in the sort order
will be deleted. 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.
operationId: edit_message
parameters:
- name: TR-Dataset
in: header
description: >-
The dataset id or tracking_id to use for the request. We assume you
intend to use an id if the value is a valid uuid.
required: true
schema:
type: string
format: uuid
requestBody:
description: JSON request payload to edit a message and get a new stream
content:
application/json:
schema:
$ref: '#/components/schemas/EditMessageReqPayload'
required: true
responses:
'200':
description: >-
This will be a HTTP stream, check the chat or search UI for an
example how to process this
headers:
TR-QueryID:
schema:
type: string
format: uuid
description: Query ID that is used for tracking analytics
'400':
description: Service error relating to getting a chat completion
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
security:
- ApiKey:
- admin
components:
schemas:
EditMessageReqPayload:
type: object
required:
- topic_id
- message_sort_order
properties:
audio_input:
type: string
description: >-
The base64 encoded audio input of the user message to attach to the
topic and then generate an assistant message in response to.
nullable: true
concat_user_messages_query:
type: boolean
description: >-
If concat user messages query is set to true, all of the user
messages in the topic will be concatenated together and used as the
search query. If not specified, this defaults to false. Default is
false.
nullable: true
context_options:
allOf:
- $ref: '#/components/schemas/ContextOptions'
nullable: true
currency:
type: string
description: >-
The currency symbol to use for the completion. If not specified,
this defaults to "$".
nullable: true
filters:
allOf:
- $ref: '#/components/schemas/ChunkFilter'
nullable: true
highlight_options:
allOf:
- $ref: '#/components/schemas/HighlightOptions'
nullable: true
image_urls:
type: array
items:
type: string
description: The URL of the image(s) to attach to the message.
nullable: true
llm_options:
allOf:
- $ref: '#/components/schemas/LLMOptions'
nullable: true
message_sort_order:
type: integer
format: int32
description: The sort order of the message to edit.
metadata:
description: >-
Metadata is any metadata you want to associate w/ the event that is
created from this request
nullable: true
model:
type: string
description: >-
Model name to use for the completion. If not specified, this
defaults to the dataset's model.
nullable: true
new_message_content:
type: string
description: The new content of the message to replace the old content with.
nullable: true
no_result_message:
type: string
description: >-
No result message for when there are no chunks found above the score
threshold.
nullable: true
number_of_messages_to_include:
type: integer
format: int64
description: >-
Number of messages to include in the context window. If not
specified, this defaults to 10.
nullable: true
minimum: 0
only_include_docs_used:
type: boolean
description: >-
Only include docs used is a boolean that indicates whether or not to
only include the docs that were used in the completion. If true, the
completion will only include the docs that were used in the
completion. If false, the completion will include all of the docs.
nullable: true
page_size:
type: integer
format: int64
description: >-
Page size is the number of chunks to fetch during RAG. If 0, then no
search will be performed. If specified, this will override the N
retrievals to include in the dataset configuration. Default is None.
nullable: true
minimum: 0
rag_context:
type: string
description: Overrides what the way chunks are placed into the context window
nullable: true
remove_stop_words:
type: boolean
description: >-
If true, stop words (specified in server/src/stop-words.txt in the
git repo) will be removed. Queries that are entirely stop words will
be preserved.
nullable: true
score_threshold:
type: number
format: float
description: >-
Set score_threshold to a float to filter out chunks with a score
below the threshold. This threshold applies before weight and bias
modifications. If not specified, this defaults to 0.0.
nullable: true
search_query:
type: string
description: >-
Query is the search query. This can be any string. The search_query
will be used to create a dense embedding vector and/or sparse vector
which will be used to find the result set. If not specified, will
default to the last user message or HyDE if HyDE is enabled in the
dataset configuration. Default is None.
nullable: true
search_type:
allOf:
- $ref: '#/components/schemas/SearchMethod'
nullable: true
sort_options:
allOf:
- $ref: '#/components/schemas/SortOptions'
nullable: true
topic_id:
type: string
format: uuid
description: The id of the topic to edit the message at the given sort order for.
typo_options:
allOf:
- $ref: '#/components/schemas/TypoOptions'
nullable: true
use_agentic_search:
type: boolean
description: >-
If true, the search will be conducted using llm tool calling. If not
specified, this defaults to false.
nullable: true
use_group_search:
type: boolean
nullable: true
use_quote_negated_terms:
type: boolean
description: >-
If true, quoted and - prefixed words will be parsed from the queries
and used as required and negated words respectively. Default is
false.
nullable: true
user_id:
type: string
description: >-
The user_id is the id of the user who is making the request. This is
used to track user interactions with the RAG results.
nullable: true
ErrorResponseBody:
type: object
required:
- message
properties:
message:
type: string
example:
message: Bad Request
ContextOptions:
type: object
description: >-
Context options to use for the completion. If not specified, all options
will default to false.
properties:
include_links:
type: boolean
description: >-
Include links in the context. If not specified, this defaults to
false.
nullable: true
ChunkFilter:
type: object
description: >-
ChunkFilter is a JSON object which can be used to filter chunks. This is
useful for when you want to filter chunks by arbitrary metadata. Unlike
with tag filtering, there is a performance hit for filtering on
metadata.
properties:
must:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
All of these field conditions have to match for the chunk to be
included in the result set.
nullable: true
must_not:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
None of these field conditions can match for the chunk to be
included in the result set.
nullable: true
should:
type: array
items:
$ref: '#/components/schemas/ConditionType'
description: >-
Only one of these field conditions has to match for the chunk to be
included in the result set.
nullable: true
example:
must:
- field: tag_set
match_all:
- A
- B
- field: num_value
range:
gte: 10
lte: 25
HighlightOptions:
type: object
description: >-
Highlight Options lets you specify different methods to highlight the
chunks in the result set. If not specified, this defaults to the score
of the chunks.
properties:
highlight_delimiters:
type: array
items:
type: string
description: >-
Set highlight_delimiters to a list of strings to use as delimiters
for highlighting. If not specified, this defaults to ["?", ",", ".",
"!"]. These are the characters that will be used to split the
chunk_html into splits for highlighting. These are the characters
that will be used to split the chunk_html into splits for
highlighting.
nullable: true
highlight_max_length:
type: integer
format: int32
description: >-
Set highlight_max_length to control the maximum number of tokens
(typically whitespace separated strings, but sometimes also word
stems) which can be present within a single highlight. If not
specified, this defaults to 8. This is useful to shorten large
splits which may have low scores due to length compared to the
query. Set to something very large like 100 to highlight entire
splits.
nullable: true
minimum: 0
highlight_max_num:
type: integer
format: int32
description: >-
Set highlight_max_num to control the maximum number of highlights
per chunk. If not specified, this defaults to 3. It may be less than
3 if no snippets score above the highlight_threshold.
nullable: true
minimum: 0
highlight_results:
type: boolean
description: >-
Set highlight_results to false for a slight latency improvement
(1-10ms). If not specified, this defaults to true. This will add
`` tags to the chunk_html of the chunks to highlight
matching splits and return the highlights on each scored chunk in
the response.
nullable: true
highlight_strategy:
allOf:
- $ref: '#/components/schemas/HighlightStrategy'
nullable: true
highlight_threshold:
type: number
format: double
description: >-
Set highlight_threshold to a lower or higher value to adjust the
sensitivity of the highlights applied to the chunk html. If not
specified, this defaults to 0.8. The range is 0.0 to 1.0.
nullable: true
highlight_window:
type: integer
format: int32
description: >-
Set highlight_window to a number to control the amount of words that
are returned around the matched phrases. If not specified, this
defaults to 0. This is useful for when you want to show more context
around the matched words. When specified, window/2 whitespace
separated words are added before and after each highlight in the
response's highlights array. If an extended highlight overlaps with
another highlight, the overlapping words are only included once.
This parameter can be overriden to respect the highlight_max_length
param.
nullable: true
minimum: 0
post_tag:
type: string
description: >-
Custom html tag which should appear after highlights. If not
specified, this defaults to ''.
nullable: true
pre_tag:
type: string
description: >-
Custom html tag which should appear before highlights. If not
specified, this defaults to ''.
nullable: true
LLMOptions:
type: object
description: >-
LLM options to use for the completion. If not specified, this defaults
to the dataset's LLM options.
properties:
completion_first:
type: boolean
description: >-
Completion first decides whether the stream should contain the
stream of the completion response or the chunks first. Default is
false. Keep in mind that || is used to separate the chunks from the
completion response. If || is in the completion then you may want to
split on ||{ instead.
nullable: true
frequency_penalty:
type: number
format: float
description: >-
Frequency penalty is a number between -2.0 and 2.0. Positive values
penalize new tokens based on their existing frequency in the text so
far, decreasing the model's likelihood to repeat the same line
verbatim. Default is 0.7.
nullable: true
image_config:
allOf:
- $ref: '#/components/schemas/ImageConfig'
nullable: true
max_tokens:
type: integer
format: int32
description: >-
The maximum number of tokens to generate in the chat completion.
Default is None.
nullable: true
minimum: 0
presence_penalty:
type: number
format: float
description: >-
Presence penalty is a number between -2.0 and 2.0. Positive values
penalize new tokens based on whether they appear in the text so far,
increasing the model's likelihood to talk about new topics. Default
is 0.7.
nullable: true
stop_tokens:
type: array
items:
type: string
description: >-
Stop tokens are up to 4 sequences where the API will stop generating
further tokens. Default is None.
nullable: true
stream_response:
type: boolean
description: >-
Whether or not to stream the response. If this is set to true or not
included, the response will be a stream. If this is set to false,
the response will be a normal JSON response. Default is true.
nullable: true
system_prompt:
type: string
description: Optionally, override the system prompt in dataset server settings.
nullable: true
temperature:
type: number
format: float
description: >-
What sampling temperature to use, between 0 and 2. Higher values
like 0.8 will make the output more random, while lower values like
0.2 will make it more focused and deterministic. Default is 0.5.
nullable: true
SearchMethod:
type: string
enum:
- fulltext
- semantic
- hybrid
- bm25
SortOptions:
type: object
description: >-
Sort Options lets you specify different methods to rerank the chunks in
the result set. If not specified, this defaults to the score of the
chunks.
properties:
location_bias:
allOf:
- $ref: '#/components/schemas/GeoInfoWithBias'
nullable: true
mmr:
allOf:
- $ref: '#/components/schemas/MmrOptions'
nullable: true
recency_bias:
type: number
format: float
description: >-
Recency Bias lets you determine how much of an effect the recency of
chunks will have on the search results. If not specified, this
defaults to 0.0. We recommend setting this to 1.0 for a gentle
reranking of the results, >3.0 for a strong reranking of the
results.
nullable: true
sort_by:
allOf:
- $ref: '#/components/schemas/QdrantSortBy'
nullable: true
tag_weights:
type: object
description: >-
Tag weights is a JSON object which can be used to boost the ranking
of chunks with certain tags. This is useful for when you want to be
able to bias towards chunks with a certain tag on the fly. The keys
are the tag names and the values are the weights.
additionalProperties:
type: number
format: float
nullable: true
use_weights:
type: boolean
description: >-
Set use_weights to true to use the weights of the chunks in the
result set in order to sort them. If not specified, this defaults to
true.
nullable: true
TypoOptions:
type: object
description: >-
Typo Options lets you specify different methods to correct typos in the
query. If not specified, typos will not be corrected.
properties:
correct_typos:
type: boolean
description: >-
Set correct_typos to true to correct typos in the query. If not
specified, this defaults to false.
nullable: true
disable_on_word:
type: array
items:
type: string
description: >-
Words that should not be corrected. If not specified, this defaults
to an empty list.
nullable: true
one_typo_word_range:
allOf:
- $ref: '#/components/schemas/TypoRange'
nullable: true
prioritize_domain_specifc_words:
type: boolean
description: >-
Auto-require non-english words present in the dataset to exist in
each results chunk_html text. If not specified, this defaults to
true.
nullable: true
two_typo_word_range:
allOf:
- $ref: '#/components/schemas/TypoRange'
nullable: true
ConditionType:
oneOf:
- $ref: '#/components/schemas/FieldCondition'
- $ref: '#/components/schemas/HasChunkIDCondition'
description: >-
Filters can be constructed using either fields on the chunk objects, ids
or tracking ids of chunks, and finally ids or tracking ids of groups.
HighlightStrategy:
type: string
enum:
- exactmatch
- v1
ImageConfig:
type: object
description: Configuration for sending images to the llm
properties:
images_per_chunk:
type: integer
description: >-
The number of Images to send to the llm per chunk that is fetched
more images may slow down llm inference time. default: 5
nullable: true
minimum: 0
use_images:
type: boolean
description: >-
This sends images to the llm if chunk_metadata.image_urls has some
value, the call will error if the model is not a vision LLM model.
default: false
nullable: true
example:
images_per_chunk: 1
use_images: true
GeoInfoWithBias:
type: object
description: >-
Location bias lets you rank your results by distance from a location. If
not specified, this has no effect. Bias allows you to determine how much
of an effect the location of chunks will have on the search results. If
not specified, this defaults to 0.0. We recommend setting this to 1.0
for a gentle reranking of the results, >3.0 for a strong reranking of
the results.
required:
- location
- bias
properties:
bias:
type: number
format: double
description: >-
Bias lets you specify how much of an effect the location of chunks
will have on the search results. If not specified, this defaults to
0.0. We recommend setting this to 1.0 for a gentle reranking of the
results, >3.0 for a strong reranking of the results.
location:
$ref: '#/components/schemas/GeoInfo'
MmrOptions:
type: object
description: >-
MMR Options lets you specify different methods to rerank the chunks in
the result set using Maximal Marginal Relevance. If not specified, this
defaults to the score of the chunks.
required:
- use_mmr
properties:
mmr_lambda:
type: number
format: float
description: >-
Set mmr_lambda to a value between 0.0 and 1.0 to control the
tradeoff between relevance and diversity. Closer to 1.0 will give
more diverse results, closer to 0.0 will give more relevant results.
If not specified, this defaults to 0.5.
nullable: true
use_mmr:
type: boolean
description: >-
Set use_mmr to true to use the Maximal Marginal Relevance algorithm
to rerank the results.
QdrantSortBy:
oneOf:
- $ref: '#/components/schemas/SortByField'
- $ref: '#/components/schemas/SortBySearchType'
description: >-
Sort by lets you specify a method to sort the results by. If not
specified, this defaults to the score of the chunks. If specified, this
can be any key in the chunk metadata. This key must be a numeric value
within the payload.
TypoRange:
type: object
description: >-
The TypoRange struct is used to specify the range of which the query
will be corrected if it has a typo.
required:
- min
properties:
max:
type: integer
format: int32
description: >-
The maximum number of characters that the query will be corrected if
it has a typo. If not specified, this defaults to 8.
nullable: true
minimum: 0
min:
type: integer
format: int32
description: >-
The minimum number of characters that the query will be corrected if
it has a typo. If not specified, this defaults to 5.
minimum: 0
FieldCondition:
type: object
description: >-
FieldCondition is a JSON object which can be used to filter chunks by a
field. This is useful for when you want to filter chunks by arbitrary
metadata. To access fields inside of the metadata that you provide with
the card, prefix the field name with `metadata.`.
required:
- field
properties:
boolean:
type: boolean
description: >-
Boolean is a true false value for a field. This only works for
boolean fields. You can specify this if you want values to be true
or false.
nullable: true
date_range:
allOf:
- $ref: '#/components/schemas/DateRange'
nullable: true
field:
type: string
description: >-
Field is the name of the field to filter on. Commonly used fields
are `timestamp`, `link`, `tag_set`, `location`, `num_value`,
`group_ids`, and `group_tracking_ids`. The field value will be used
to check for an exact substring match on the metadata values for
each existing chunk. This is useful for when you want to filter
chunks by arbitrary metadata. To access fields inside of the
metadata that you provide with the card, prefix the field name with
`metadata.`.
geo_bounding_box:
allOf:
- $ref: '#/components/schemas/LocationBoundingBox'
nullable: true
geo_polygon:
allOf:
- $ref: '#/components/schemas/LocationPolygon'
nullable: true
geo_radius:
allOf:
- $ref: '#/components/schemas/LocationRadius'
nullable: true
match_all:
type: array
items:
$ref: '#/components/schemas/MatchCondition'
description: >-
Match all lets you pass in an array of values that will return
results if all of the items match. The match value will be used to
check for an exact substring match on the metadata values for each
existing chunk. If both match_all and match_any are provided, the
match_any condition will be used.
nullable: true
match_any:
type: array
items:
$ref: '#/components/schemas/MatchCondition'
description: >-
Match any lets you pass in an array of values that will return
results if any of the items match. The match value will be used to
check for an exact substring match on the metadata values for each
existing chunk. If both match_all and match_any are provided, the
match_any condition will be used.
nullable: true
range:
allOf:
- $ref: '#/components/schemas/Range'
nullable: true
example:
field: metadata.key1
match:
- value1
- value2
range:
gt: 0
gte: 0
lt: 1
lte: 1
HasChunkIDCondition:
type: object
description: >-
HasChunkIDCondition is a JSON object which can be used to filter chunks
by their ids or tracking ids. This is useful for when you want to filter
chunks by their ids or tracking ids.
properties:
ids:
type: array
items:
type: string
format: uuid
description: >-
Ids of the chunks to apply a match_any condition with. Only chunks
with one of these ids will be returned.
nullable: true
tracking_ids:
type: array
items:
type: string
description: >-
Tracking ids of the chunks to apply a match_any condition with. Only
chunks with one of these tracking ids will be returned.
nullable: true
GeoInfo:
type: object
description: Location that you want to use as the center of the search.
required:
- lat
- lon
properties:
lat:
$ref: '#/components/schemas/GeoTypes'
lon:
$ref: '#/components/schemas/GeoTypes'
SortByField:
type: object
required:
- field
properties:
direction:
allOf:
- $ref: '#/components/schemas/SortOrder'
nullable: true
field:
type: string
description: >-
Field to sort by. This has to be a numeric field with a Qdrant
`Range` index on it. i.e. num_value and timestamp
prefetch_amount:
type: integer
format: int64
description: How many results to pull in before the sort
nullable: true
minimum: 0
SortBySearchType:
type: object
required:
- rerank_type
properties:
prefetch_amount:
type: integer
format: int64
description: How many results to pull in before the rerabj
nullable: true
minimum: 0
rerank_query:
type: string
description: Query to use for prefetching defaults to the search query
nullable: true
rerank_type:
$ref: '#/components/schemas/ReRankOptions'
DateRange:
type: object
description: >-
DateRange is a JSON object which can be used to filter chunks by a range
of dates. This leverages the time_stamp field on chunks in your dataset.
You can specify this if you want values in a certain range. You must
provide ISO 8601 combined date and time without timezone.
properties:
gt:
type: string
nullable: true
gte:
type: string
nullable: true
lt:
type: string
nullable: true
lte:
type: string
nullable: true
example:
gt: '2021-01-01 00:00:00.000'
gte: '2021-01-01 00:00:00.000'
lt: '2021-01-01 00:00:00.000'
lte: '2021-01-01 00:00:00.000'
LocationBoundingBox:
type: object
required:
- top_left
- bottom_right
properties:
bottom_right:
$ref: '#/components/schemas/GeoInfo'
top_left:
$ref: '#/components/schemas/GeoInfo'
LocationPolygon:
type: object
required:
- exterior
properties:
exterior:
type: array
items:
$ref: '#/components/schemas/GeoInfo'
interior:
type: array
items:
type: array
items:
$ref: '#/components/schemas/GeoInfo'
nullable: true
LocationRadius:
type: object
required:
- center
- radius
properties:
center:
$ref: '#/components/schemas/GeoInfo'
radius:
type: number
format: double
MatchCondition:
oneOf:
- type: string
- type: integer
format: int64
- type: number
format: double
Range:
type: object
properties:
gt:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
gte:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
lt:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
lte:
allOf:
- $ref: '#/components/schemas/RangeCondition'
nullable: true
example:
gt: 0
gte: 0
lt: 1
lte: 1
GeoTypes:
oneOf:
- type: integer
format: int64
- type: number
format: double
SortOrder:
type: string
enum:
- desc
- asc
ReRankOptions:
type: string
enum:
- semantic
- fulltext
- bm25
- cross_encoder
RangeCondition:
oneOf:
- type: number
format: double
- type: integer
format: int64
securitySchemes:
ApiKey:
type: apiKey
in: header
name: Authorization
````