Quick Reference

A summary of all endpoints available in the deepset Cloud API and their purpose.

Public Endpoints

For these endpoints, we maintain the same schema.

Collection Overview

healthChecking the connection.
api_tokenCreating an API key to connect deepset Cloud to your app.
eval_runManaging evaluation runs (also known as experiments). This includes creating, deleting, starting, and listing evaluation runs.
evaluation_setImporting, listing, and deleting evaluation datasets.
fileWorking with files in deepset Cloud.
document_storeListing and searching for documents in the document store.
pipelineManaging your pipelines. This includes
upload_sessionOpening, closing, and checking the status of the upload sessions used to upload files with the SDK. For more information, see Tutorial: Uploading Files with Python Methods.

Endpoints List

The base URL for all endpoints, except for health is https://api.cloud.deepset.ai/api/v1.

Resource Method Endpoint Description
Health GET /health Checks the connection.
API token POST /token Creates an API token you can use to connect deepset Cloud to your app.
Evaluation Run GET /workspaces/{workspace_name}/eval_runs Returns all existing evaluation runs.
GET /workspaces/{workspace_name}/eval_runs/{eval_run_name} Returns the eval run you indicate.
GET /workspaces/{workspace_name}/eval_runs/{eval_run_name}/nodes/{node_name}/predictions Returns the answers form a given node.
POST /workspaces/{workspace_name}/eval_runs Creates an evaluation run.
POST /workspaces/{workspace_name}/eval_runs/{eval_run_name}/start Starts an evaluation run.
PATCH /workspaces/{workspace_name}/eval_runs/{eval_run_name} Updates an evaluation run.
DELETE /workspaces/{workspace_name}/eval_runs/{eval_run_name} Deletes an evaluation run.
Evaluation Set GET /workspaces/{workspace_name}/evaluation_sets REturns all existing evaluation sets.
GET /workspaces/{workspace_name}/evaluation_sets/{evaluation_set_name} Returns the contents of an evaluation set.
GET /workspaces/{workspace_name}/evaluation_sets/{evaluation_set_name}/csv Returns an evaluation set as a CSV file.
POST /workspaces/{workspace_name}/evaluation_sets/import Imports an evaluation set.
POST /workspaces/{workspace_name}/evaluation_sets/{evaluation_set_name}/label-matching Triggers matching labels from the eval set to the files in deepset Cloud.
DELETE /workspaces/{workspace_name}/evaluation_sets/{evaluation_set_name} Deletes an evaluation set.
File GET /workspaces/{workspace_name}/files Lists all files
GET /workspaces/{workspace_name}/files/{file_id} Returns the contents of the file.
GET /workspaces/{workspace_name}/files/{file_id}/meta Returns file metadata.
POST /workspaces/{workspace_name}/files Uploads or creates a text file.
PATCH /workspaces/{workspace_name}/files/{file_id}/meta Updates file metadata.
DELETE /workspaces/{workspace_name}/files Deletes multiple files.
DELETE /workspaces/{workspace_name}/files/{file_id} Deletes a single file.
Document Store POST /workspaces/{workspace_name}/indexes/{index_name}/documents-query Searches the documents based on a query.
POST /workspaces/{workspace_name}/indexes/{index_name}/documents-stream Returns all documents for a pipeline.
Pipeline GET /workspaces/{workspace_name}/pipelines Lists all pipelines.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name} Returns a pipeline.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/feedback Returns feedback for a pipeline.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/files Returns file IDs for a pipeline.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/indexing Returns pipeline indexing status.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/json Returns a pipeline as JSON.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/prompt Returns pipeline prompt.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/stats Returns pipeline statistics.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/yaml Returns pipeline as YAML.
POST /workspaces/{workspace_name}/pipelines Creates a pipeline YAML.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/chat Runs a chat.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/default Sets a default pipeline for search.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/deploy Deploys a pipeline.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/feedback Adds feedback to search results.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/search Runs a search.
POST /workspaces/{workspace_name}/pipelines/{pipeline_name}/undeploy Undeploys a pipeline.
PATCH /workspaces/{workspace_name}/pipelines/{pipeline_name} Updates pipeline properties.
PUT /workspaces/{workspace_name}/pipelines/{pipeline_name}/yaml Updates pipeline YAML.
DELETE /workspaces/{workspace_name}/pipelines/{pipeline_name} Deletes a pipeline.
Upload Session GET /workspaces/{workspace_name}/upload_sessions Returns all active upload sessions.
GET /workspaces/{workspace_name}/upload_sessions/{session_id} Shows the details of a session.
GET /workspaces/{workspace_name}/upload_sessions/{session_id}/files Returns session files.
POST /workspaces/{workspace_name}/upload_sessions Creates an upload session.
PUT /workspaces/{workspace_name}/upload_sessions/{session_id} Closes the upload session.

Private Endpoints

The schema may change for these endpoints. This means the structure, format, or data sent or received at those endpoints, may change.

Collection Overview

infrastructureManaging the connection to your VPC.
userListing and deleting users. Updating user permissions.
modelsListing models available for a node.
model_registry_tokenWorking with tokens for private models.
notebookCreating, listing, and starting Jupyter Lab notebooks.
organizationListing deepset Cloud organizations and adding users to them.
promptsManaging prompt templates.
api_tokenListing and deleting API keys.
workspaceWorking with deepset Cloud workspaces. This includes, creating, listing, and viewing workspace statistics.
eval_runManaging tags added to evaluation runs.
document_storeChecking the connection, getting a document, and counting the total number of documents.
labeling_projectCreating, listing, updating, and deleting labeling projects used for preparing evaluation datasets.
pipeline_templatesListing all templates.
pipelineValidating pipelines, getting metadata of indexed files, logs, and search history.
search_sessionListing and creating search sessions. Search sessions are used for chat.
shared_prototypeManaging shared prototypes of your pipelines.

Endpoints List

The base URL for all endpoints is https://api.cloud.deepset.ai/api/v1.

Resource Method Endpoint Description
Infrastructure GET /infrastructure/document_stores Lists existing Opensearch credentials.
GET /infrastructure/file_stores Lists existing S3 bucket credentials.
POST /infrastructure/document_stores Adds your Opensearch cluster credentials.
POST /infrastructure/file_stores Adds your S3 bucket credentials.
DELETE /infrastructure/document_stores/{credentials_id} Deletes Opensearch credentials.
DELETE /infrastructure/file_stores/{credentials_id} Deletes S3 credentials.
User GET /me Gets current user properties.
GET /users Gets properies of all users.
GET /users/{user_id} Gets properies of a specified user.
GET /me Gets user properties.
GET /me Gets user properties.
Models GET /model Returns a list of models available for a node.
Model registry token GET /model_registry_tokens Returns all model tokens.
GET /model_registry_tokens/{provider} Returns the model token from a specific provider.
POST /model_registry_tokens/{provider} Imports and saves the model token from a specific provider.
PUT /model_registry_tokens/{provider} Imports and saves the model token from a specific provider.
DELETE /model_registry_tokens/{provider} Deletes the model token from a specific provider.
Notebook GET /notebook-server Returns the status of the Jupyter lab server.
POST /notebook Creates a Jupyter notebook.
POST /notebook-server Opens the Jupyter lab.
Organization GET /organization Returns the name of the organization.
POST /organization/{organization_id}/invitation Invites a user to a deepset Cloud organization.
Prompts GET /public_prompt_templates Lists public prompt templates.
GET /workspaces/{workspace_name}/prompt_templates Lists prompt templates for a given workspace.
POST /trigger_prompthub_sync Syncs prompts from Prompt Hub.
POST /workspaces/{workspace_name}/prompt_templates Creates a prompt template.
PUT /workspaces/{workspace_name}/prompt_templates/{prompt_template_id} Updates the specified prompt template.
DELETE /workspaces/{workspace_name}/prompt_templates/{prompt_template_id} Deletes a specified prompt template.
API Token GET /token Returns all existing API keys.
GET /workspaces/{workspace_name}/upload_sessions/{session_id} Shows the details of a session.
DELETE /token/{api_token_id} Deletes the specified API key.
Workspace GET /workspaces Lists all workspaces.
GET /workspaces/{workspace_name} Returns the workspace and its properties.
GET /workspaces/{workspace_name}/search_count Returns the number of search requests.
GET /workspaces/{workspace_name}/search_history Returns search history.
GET /workspaces/{workspace_name}/stats Returns worskpace statistics.
POST /workspaces Creates a workspace.
DELETE /workspaces/{workspace_name} Deletes a workspace.
Eval Run GET /workspaces/{workspace_name}/tags Lists all eval run tags.
POST /workspaces/{workspace_name}/tags Creates eval run tags.
PATCH /workspaces/{workspace_name}/tags/{tag_name} Updates tags.
DELETE /workspaces/{workspace_name}/tags/{tag_name} Deletes a tag.
Document Store GET /workspaces/{workspace_name}/indexes/{index_name} Checks the connection with OpenSearch.
GET /workspaces/{workspace_name}/indexes/{index_name}/documents/{document_id} Returns the contents of a document and its properties.
POST /workspaces/{workspace_name}/indexes/{index_name}/documents-count Returns the number of documents for a pipeline.
Labeling Project GET /workspaces/{workspace_name}/labeling_projects Lists all labeling projects.
GET /workspaces/{workspace_name}/labeling_projects/{labeling_project_id} Returns a labeling project.
POST /workspaces/{workspace_name}/labeling_projects Creates a labeling project.
PUT /workspaces/{workspace_name}/labeling_projects/{labeling_project_id} Updates a labeling project.
DELETE /workspaces/{workspace_name}/labeling_projects/{labeling_project_id} Deletes a labeling project.
Pipeline Templates GET /workspaces/{workspace_name}/pipeline_templates Lists all pipeline templates.
Pipeline GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/logs Returns pipeline logs.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/meta Returns metadata keys of indexed files.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/meta/{field_name} Returns metadata values of indexed files.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/meta/{meta_field}/aggregation Returns the minimum and maximum aggregation of a metadata field.
GET /workspaces/{workspace_name}/pipelines/{pipeline_name}/search_history Returns pipeline search history.
Search Session GET /workspaces/{workspace_name}/search_sessions Lists search sessions.
POST /workspaces/{workspace_name}/search_sessions Creates a search session.
Shared Prototype GET /workspaces/{workspace_name}/shared_prototypes Lists shared prototypes.
GET /workspaces/{workspace_name}/shared_prototypes/{shared_prototype_id} Returns a single shared prototype.
POST /workspaces/{workspace_name}/shared_prototype_users Creates a shared prototype user.
POST /workspaces/{workspace_name}/shared_prototypes Creates a shared prototype.
PATCH /workspaces/{workspace_name}/shared_prototypes/{shared_prototype_id} Updates a shared prototype.
DELETE /workspaces/{workspace_name}/shared_prototypes/{shared_prototype_id} Deletes a shared prototype.