Private AI Services API Operations Index
All available Private AI Services API Operations
This method allows you to list all agents that have been configured.
This method allows you to create a new agent. The agent requires an LLM to be used for generating completions, so you need to make sure the corresponding Model Endpoint has been deployed in the same namespace as this PAIS instance. You can use the List Models method to view all available LLMs.
An agent can also be configured to use an index to enhance the context that is sent to the LLM. You can use the List indexes across all knowledge bases method to view all available knowledge base indexes that you can use.
This method allows you to list all agents that have been configured.
This method allows you to create a new agent. The agent requires an LLM to be used for generating completions, so you need to make sure the corresponding Model Endpoint has been deployed in the same namespace as this PAIS instance. You can use the List Models method to view all available LLMs.
An agent can also be configured to use an index to enhance the context that is sent to the LLM. You can use the List indexes across all knowledge bases method to view all available knowledge base indexes that you can use.
This method allows you to retrieve the configuration of an agent identified by its ID. The response also includes the current status of the agent, such as if the agent is configured to use an LLM or index that is currently unavailable.
This method allows you to update a previously created agent using its ID.
You can obtain the ID of the agent to update either from the API response when you created the agent, or by listing the available agents.
It is sufficient to provide the fields that should be changed. To reset/remove a
property from the agent, use the null value.
This method allows you to delete a previously created agent using its ID.
You can obtain the ID of the agent to delete either from the API response when you created the agent, or by listing the available agents.
This method allows you to retrieve the configuration of an agent identified by its ID. The response also includes the current status of the agent, such as if the agent is configured to use an LLM or index that is currently unavailable.
This method allows you to update a previously created agent using its ID.
You can obtain the ID of the agent to update either from the API response when you created the agent, or by listing the available agents.
It is sufficient to provide the fields that should be changed. To reset/remove a
property from the agent, use the null value.
This method allows you to delete a previously created agent using its ID.
You can obtain the ID of the agent to delete either from the API response when you created the agent, or by listing the available agents.
This method creates a model response for the given chat conversation. The conversation is updated to reflect the agent settings and to use any inputs from enabled integrations, before it is forwarded to the LLM.
This method is compatible with the OpenAI endpoint for creating a chat completion. However, it infers additional inputs to the conversation as described above.
This method creates a model response for the given chat conversation. The conversation is updated to reflect the agent settings and to use any inputs from enabled integrations, before it is forwarded to the LLM.
This method is compatible with the OpenAI endpoint for creating a chat completion. However, it infers additional inputs to the conversation as described above.
Given a prompt, this method lets you retrieve one or more predicted completions along with the probabilities of alternative tokens at each position. The prompt is updated to reflect the agent settings and to use any inputs from enabled integrations, before it is forwarded to the LLM.
To leverage the newest models and features, you should consider using use the Chat Completions API instead.
This method is compatible with the OpenAI endpoint for creating a completion. However, it infers additional inputs to the prompt as described above.
Given a prompt, this method lets you retrieve one or more predicted completions along with the probabilities of alternative tokens at each position. The prompt is updated to reflect the agent settings and to use any inputs from enabled integrations, before it is forwarded to the LLM.
To leverage the newest models and features, you should consider using use the Chat Completions API instead.
This method is compatible with the OpenAI endpoint for creating a completion. However, it infers additional inputs to the prompt as described above.
This endpoint allows you to test if a data source has been configured correctly.
More specifically, the API will attempt to connect to the data source as it would when the PAIS backend performs an indexing. This allows you to verify whether the stored settings and credentials are correct and the PAIS system can connect to the data source APIs.
You can use this endpoint, for example, to ensure that updates to settings or credentials will allow the next indexing to access the data source.
To test the configuration before creating the data source, you can instead use the
/test-connection endpoint.
This endpoint allows you to test if a given configuration can be used for a data source.
More specifically, the API will attempt to connect to a data source using the provided configuration, as it would during an indexing. This allows you to verify whether the stored settings and credentials are correct and the PAIS system can connect to the data source APIs, even before creating the data source.
To test the configuration of an existing data source, you can instead use the
/test-connection/<data-source> endpoint.
This method allows you to list all data sources that have been configured.
Note that it is not possible to retrieve the configured credentials (if any) of a data source.
This method allows you to create a new data source.
This method allows you to retrieve the configuration of a data source identified by its ID.
Note that it is not possible to retrieve the configured credentials (if any) of the data source.
This method allows you to update a previously created data source using its ID.
You can obtain the ID of the data source to update either from the API response when you created the data source, or by listing the available data sources.
It is sufficient to provide the fields that should be changed. To reset/remove a
property from the data source, use the null value.
This method allows you to delete a previously created data source using its ID.
You can obtain the ID of the data source to delete either from the API response when you created the data source, or by listing the available data sources.
Note that data sources that are linked to a knowledge base cannot be deleted. If you attempt to do so, the API will raise an error. In this case, you have to unlink the data source from all knowledge bases before being able to delete it.
This method allows you to list all knowledge bases linked to a specific data source.
This method is useful if you want to understand which knowledge bases are using a data source - for example, to understand which knowledge bases are referencing a data source and need to be unlinked in order to allow deletion.
This method allows you to list all indexes across all knowledge bases.
For details, refer to the method to List all indexes for a knowledge base.
This method allows you to create an index for a knowledge base.
The index defines how document contents are embedded. For example, it allows you
to define the embeddings model to use by specifying the routing_name of the
Model Endpoint to use. Additionally, you can specify how to divide the contents
of each document into smaller "chunks"; bigger chunks may provide better context
when they are sent to an LLM for answering questions, but smaller chunks may help
identify and select relevant document parts.
Choosing the right embedding model and best chunking strategy depends on your data
and use-case and may require some experimentation.
Note that you cannot modify an index after its creation. The reason is that all documents in an index must be embedded in the same way. If core properties of the index (such as the embeddings model in use) are changed after the initial insert, it would no longer be possible to meaningfully search, compare, or rank embeddings in the index.
This method allows you to list all indexes of a knowledge base.
For each index in the list, the response also contains metadata, such as
how many documents have been added to the index, or what is the status
of the index. The status of an index is determined by the status of the
embedding model; if the model becomes unavailable, the status of the index
is updated. The details are reflected in the status_errors.
This method allows you to retrieve the configuration of an index identified by its ID.
The response also contains metadata, such as how many documents have been added to
the index, or what is the status of the index. The status of an index is determined
by the status of the embedding model; if the model becomes unavailable, the status of
the index is updated. The details are reflected in the status_errors.
This method allows you to search for documents in an index that are relevant to a particular search input.
The request allows you specify a particular text which is then embedded using
the index configuration. The API will search through all indexed documents and
find chunks that match the content of text. More specifically, the API will find
any chunk with a small vector-distance between the embedded text and the embedded
document chunk content.
The document chunks that are most closely related to the provided text are returned
in the response, and the API will return up to top_k chunks. Additionally, you can
further limit which chunks are returned by specifying a via similarity_cutoff, which
means that only chunks that meet a minimum similarity are included in the response.
The response includes, for each chunk that was found, metadata about the document from which the chunk was extracted. This provides a link back to the document that was added to the index.
This method allows you to identify which indexing contains the most relevant data for a particular index.
The indexing that is considered "most relevant" for a given index is the indexing that is actively running (i.e., the backend is processing documents), or the most recently completed indexing, if no indexing is running or has been queued.
If no indexing is actively running or has been completed yet, the oldest pending indexing (if any) is considered to be the "most relevant".
You can use this method to identify which indexing to choose for determining the indexing status of a knowledge base index. The same can be accomplished by listing all indexings of a knowledge base index, but it abstracts away the logic of identifying which indexing you want to monitor.
Note that the returned indexing can change over time, as indexings complete and queued indexings are started.
This method allows you to list all for documents in an index.
Each document contains metadata, which tells you from which data source the document was retrieved (if any), what is the status of the document (if it has already been indexed, if indexing is pending, or if indexing may have failed), and what the system inferred to be the type of the document.
This method allows you to upload a document to an index.
If the document is accepted by the API, the system will automatically trigger an indexing to process the document and add its document chunks to the index. To check the indexing progress and status, you can use the methods for listing documents or retrieving the document by its ID.
Once the indexing of the uploaded document is complete, only the document metadata and any embedded chunks are stored. The original, uploaded document is deleted.
Note that you can only upload documents to an index for a knowledge base that
was created with data_origin_type=LOCAL_FILES. For details, refer to the method
to Create a new knowledge base.
This method allows you to remove a document from an index.
When a document is removed, its embeddings (if any) are removed from the vector-store associated with the index, and its chunks will no-longer appear in any search result.
Note that you can only remove documents from an index for a knowledge base that
was created with data_origin_type=LOCAL_FILES. For details, refer to the method
to Create a new knowledge base.
To remove documents from any other type of index, remove the documents from the underlying data source and trigger a new indexing. Any document that is not found in the data source will be removed automatically as part of the indexing.
This method allows you to get a document in an index using its ID.
The document contains metadata, which tells you from which data source the document was retrieved (if any), what is the status of the document (if it has already been indexed, if indexing is pending, or if indexing may have failed), and what the system inferred to be the type of the document.
This method allows you to trigger an indexing for a knowledge base index.
As part of an indexing, all data sources linked to the knowledge base of the index are crawled, and any previously-unseed documents are downloaded, they are added to the index, and are subsequently processed. Any documents that have been previously added to an index and that are no-longer available in the data source are removed from the index.
As part of processing a document, the system extracts and embeds chunks, as configured for the index. Once a document has been processed and its metadata and chunks have been stored, the original, downloaded document is removed from memory and storage (the original files remain on the data source are never modified or deleted).
Depending on the number of documents, an indexing can take a significant amount of time. An indexing is considered complete once all documents from a data source been crawled, once all discovered documents have been processed fully, and once any document removed from the data source has been removed from the index.
Note that you can only trigger an indexing for an index of a knowledge base index
that was created with data_origin_type=DATA_SOURCES. For any other type of
index, an indexing is triggered automatically when documents are uploaded to
the index via the API. For details, refer to the method to Add a document to
an index.
Note that you can only run one indexing per index at any point in time. If an indexing is currently running when you create a new one, the newly created indexing will be queued until the running indexing completes. If an indexing is already queued, creating another indexing will result in an error (as there is no need to queue a second indexing).
This method allows you to get information on all indexings of an index.
For each indexing, the returned information includes the status (if the indexing is queued, if it is actively running, or if it has completed) and other metadata.
This method allows you to get information on an indexing using its ID.
The returned information includes the status (if the indexing is queued, if it is actively running, or if it has completed) and other metadata.
This method allows you to cancel an indexing for a knowledge base index.
Depending on the number of documents to be processed, an indexing can take a significant amount of time. If you discover that the processing of documents is not happening as you expect (e.g., a data source linked to the knowledge base of the index is misconfigured, and documents fail to be downloaded), it may be useful to cancel the processing of any remaining documents.
This method allows to do so, which stops the crawling of documents from
all data sources linked to the knowledge base of the index (unless the crawling
phase is already complete), it stops the processing of any documents that
have not yet been processed, and the backend marks each such document
with status=CANCELLED.
Note that cancelling is not immediate, as any pending document needs to updated as described above. For very large knowledge bases, even cancellation may take several minutes.
Once an indexing is cancelled and any remaining processing has been completed, the indexing status is updated according, and you can trigger a new indexing.
This method also allows forcing the immediate cancellation of an indexing, which merely marks an indexing as cancelled, which allows you to trigger a new indexing. You should never require to force-cancel an indexing, and you should always perform a "regular" cancellation prior to forcing it. Only use a forced cancellation if instructed to do so by PAIS support.
This method allows you to get an aggregated view of errors that occurred during an indexing.
The errors are aggregated into buckets by the type of error and what is the source of the error. For each bucket, the response contains a description of the error and how many errors and documents are aggregated into this bucket.
For details on indexing errors, refer to the method to Get an indexing error by its ID.
This method allows you to details about an error that occurred during an indexing by its ID.
When documents are processed as part of an indexing, the PAIS system has to perform several steps.
First, if the knowledge base of the index is linked to a data source, it must find all
documents that are part of the data source. If this step fails (e.g., if the settings
or credentials of the data source are invalid), the an indexing error is reported for
the indexing. This indexing error is linked to the data source, for which crawling
failed. The source of the indexing error is set to DATA_SOURCE to indicate that
the most likely culprit is the data source configuration.
If crawling succeeds, all documents that have not yet been processed for an index are downloaded. If this fails for any document, an indexing error is reported similar to how errors are reported during the crawling phase, but the indexing error is additionally linked to the document that failed to be processed.
Next, each downloaded document is parsed to extract text, and the text is chunked
according to the index configuration. If this step fails (e.g., if the document cannot
be parsed successfully, if the system fails to identify the type of document, or if
the document type is not supported), an indexing error is reported and linked to the
corresponding document. The source of the indexing error is set to DOCUMENT to indicate
that the problem lies in the document itself.
Last, each document chunk is embedded using the configured embedding model and stored
into the index. If this step fails (e.g., if the embedding model is unavailable, or if
storing the generated data fails), an indexing error is reported. The source of the
indexing error is set to INDEXING to indicate that the problem lies with the indexing
or the index itself - as neither the data source nor the document are causing the
specific problem.
Thus, when you are diagnosing why an indexing fails, it is important to consider the
source of the indexing error.
Each indexing error contains a well-documented code property that identifies what
the exact error is that was encountered. Additionally, the system_message contains
error details, if the PAIS system interacted with a third-party component and that
component returned an error message. The op_id allows to correlate an error with
system logs of the PAIS installation.
The system_message and op_id are typically only necessary when requesting assistance
from PAIS support, and for most troubleshooting, the code should be sufficient.
For details on indexings, refer to the method to Trigger an indexing.
This method allows you to get all errors that occurred during an indexing.
For details on indexing errors, refer to the method to Get an indexing error by its ID.
This method allows you to retrieve the configuration of a knowledge base identified by its ID.
The response also contains metadata, such as how many data sources are linked to the knowledge base, or how many agents make use of an index of this knowledge base.
This method allows you to update a previously created knowledge base using its ID.
You can obtain the ID of the knowledge base to update either from the API response when you created the knowledge base, or by listing the available knowledge bases.
It is sufficient to provide the fields that should be changed. To reset/remove a
property from the knowledge base, use the null value.
Note that some properties of the knowledge base, such as its type, cannot be changed after the creation. For details, refer to the method to Create a new knowledge base.
This method allows you to delete a previously created knowledge base using its ID.
You can obtain the ID of the knowledge base to delete either from the API response when you created the knowledge base, or by listing the available knowledge bases.
Note that knowledge bases that are in use by an agent cannot be deleted. If you attempt to do so, the API will raise an error. In this case, you have to unlink the knowledge base from all agents before being able to delete it.
This method allows you to list all knowledge bases that have been configured.
For each knowledge base in the list, the response also contains metadata, such as how many data sources are linked to the knowledge base, or how many agents make use of an index of this knowledge base.
This method allows you to create a new knowledge base.
A knowledge base can be created using one of two types: a knowledge base can either
be linked to data sources (by using data_origin_type=DATA_SOURCES), or it can be
maintained independently of data sources (by using data_origin_type=LOCAL_FILES).
If a knowledge base is linked to one or more data sources, it is automatically
filled with data by crawling and retrieving documents from the linked data sources.
If documents are added or removed from a data source, the indexes of the
knowledge base are updated automatically when an indexing is triggered.
An indexing can be triggered explicitly via the API, or it can be configured to
happen periodically using an index_refresh_policy.
Otherwise, if a knowledge base not linked, you can maintain the knowledge base contents yourself. You can add documents by uploading them via the API, and uploaded documents can be removed using the API.
Note that the type of knowledge base cannot be changed after the creation, and it is not possible to mix the two types (e.g., link a knowledge base to a set of data sources and also upload files via the API).
This method allows you to get information about the link between data sources and a knowledge base, and the status of this link. For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to remove the link between a data source and a knowledge base.
For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to list all data sources linked to a specific knowledge base.
This method is useful, if you want to understand what data sources are contributing documents to a knowledge base. For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to link a data source to a knowledge base.
When you link a data source to a knowledge base, the initial status of the
link is NOT_INDEXED. This means that the data source is linked to the
knowledge base, but none of the documents in the data source have been added
to an index of the knowledge base yet.
Once you trigger an indexing, or the refresh policy triggers an indexing
automatically, documents from the data source are added to the index, and
the status of the link is updated to INDEXED.
Similarly, when you unlink a data source from the knowledge base, the status
of the link becomes PENDING_UNLINKING, because there may still be documents
from the data source in the index. Once you trigger a new indexing (or an
indexing is started automatically due to the refresh policy), the status
of the link is updated to UNLINKING.
Once all documents from a data source have been removed from the index, the link is removed.
Note that you can undo the removal of the link between a data source and the knowledge base prior to triggering an indexing (as no modifications to any index has been triggered yet). For details, refer to the method to Cancel unlinking a data source and a knowledge base.
This method allows you to cancel the removal of a link between a data source and a knowledge base.
For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to link multiple data sources to a knowledge base using a single request.
For each data source in the request, the response will show you the status of the link between the data source and the knowledge base, or it will provide you with details why linking failed.
For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to remove the link between multiple data sources and a knowledge base using a single request.
For each data source in the request, the response will show you the status of the link between the data source and the knowledge base, or it will provide you with details why unlinking failed.
For details, refer to the method to Create a link between a data source and a knowledge base.
This method allows you to cancel the removal of the link between multiple data sources and a knowledge base using a single request.
For each data source in the request, the response will show you the status of the link between the data source and the knowledge base, or it will provide you with details why cancelling the unlinking failed.
For details, refer to the method to Create a link between a data source and a knowledge base.
This method lets you list the currently available models. It further provides basic information about each model, such as the model type and the inference engine that is serving the model.
This method is compatible with the OpenAI endpoint for listing models.
This method lets you generate a vector representation of a given input. It is compatible with the OpenAI endpoint for creating embeddings.
Given a prompt, this method lets you retrieve one or more predicted completions along with the probabilities of alternative tokens at each position.
To leverage the newest models and features, you should consider using use the Chat Completions API instead.
This method is compatible with the OpenAI endpoint for creating a completion.
This method creates a model response for the given chat conversation, and it is compatible with the OpenAI endpoint for creating a chat completion.
This method allows you to list all time zones recognized by the API. It also provides the offset (in seconds) from UTC for each timezone. The names of the supported timezones are important, for example, when you want to configure refresh policies or other configurations that require specifying a timezone.
Note that all timestamps returned by the API are always in UTC and do not require a timezone.