> ## 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.
# Create Organization Api Key
> Create a new api key for the organization. Successful response will contain the newly created api key.
## OpenAPI
````yaml post /api/organization/api_key
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/organization/api_key:
post:
tags:
- Organization
summary: Create Organization Api Key
description: >-
Create a new api key for the organization. Successful response will
contain the newly created api key.
operationId: create_organization_api_key
parameters:
- name: TR-Organization
in: header
description: The organization id to use for the request.
required: true
schema:
type: string
format: uuid
requestBody:
description: JSON request payload to create a new organization api key
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyReqPayload'
required: true
responses:
'200':
description: JSON body representing the api_key for the organization
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyResponse'
'400':
description: Service error relating to creating api_key for the organization
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
security:
- ApiKey:
- readonly
components:
schemas:
CreateApiKeyReqPayload:
type: object
required:
- name
- role
properties:
dataset_ids:
type: array
items:
type: string
format: uuid
description: >-
The dataset ids which the api key will have access to. If not
provided or empty, the api key will have access to all datasets in
the dataset.
nullable: true
default_params:
allOf:
- $ref: '#/components/schemas/ApiKeyRequestParams'
nullable: true
expires_at:
type: string
description: >-
The expiration date of the api key. If not provided, the api key
will not expire. This should be provided in UTC time.
nullable: true
name:
type: string
description: The name which will be assigned to the new api key.
role:
type: integer
format: int32
description: >-
The role which will be assigned to the new api key. Either 0 (read),
1 (Admin) or 2 (Owner). The auth'ed user must have a role greater
than or equal to the role being assigned.
scopes:
type: array
items:
type: string
description: >-
The routes which the api key will have access to. If not provided or
empty, the api key will have access to all routes. Specify the
routes as a list of strings. For example, ["GET /api/dataset", "POST
/api/dataset"].
nullable: true
CreateApiKeyResponse:
type: object
required:
- api_key
properties:
api_key:
type: string
description: >-
The api key which was created. This is the value which should be
used in the Authorization header.
ErrorResponseBody:
type: object
required:
- message
properties:
message:
type: string
example:
message: Bad Request
ApiKeyRequestParams:
type: object
description: >-
The default parameters which will be forcibly used when the api key is
given on a request. If not provided, the api key will not have default
parameters.
properties:
filters:
allOf:
- $ref: '#/components/schemas/ChunkFilter'
nullable: true
highlight_options:
allOf:
- $ref: '#/components/schemas/HighlightOptions'
nullable: true
no_result_message:
type: string
description: >-
Options for handling the response for the llm to return when no
results are found
nullable: true
page_size:
type: integer
format: int64
description: >-
Page size is the number of chunks to fetch. This can be used to
fetch more than 10 chunks at a time.
nullable: true
minimum: 0
remove_stop_words:
type: boolean
description: >-
If true, stop words 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.
nullable: true
search_type:
allOf:
- $ref: '#/components/schemas/SearchMethod'
nullable: true
slim_chunks:
type: boolean
description: >-
Set slim_chunks to true to avoid returning the content and
chunk_html of the chunks.
nullable: true
typo_options:
allOf:
- $ref: '#/components/schemas/TypoOptions'
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.
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
SearchMethod:
type: string
enum:
- fulltext
- semantic
- hybrid
- bm25
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
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
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
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'
RangeCondition:
oneOf:
- type: number
format: double
- type: integer
format: int64
GeoTypes:
oneOf:
- type: integer
format: int64
- type: number
format: double
securitySchemes:
ApiKey:
type: apiKey
in: header
name: Authorization
````