Skip to main content

API Documentation

deepset AI Platform API endpoints are grouped into two main collections:

  • Main API: Core features and feedback endpoints.
  • Jobs API: Job management endpoints.

Structure and Organization​

deepset AI Platform API uses REST-based architecture to offer intuitive and predictable structure. The URLs are structured to be resource-oriented and easy to understand. The API returns JSON responses using standard HTTP response codes.

The API uses the standard HTTP verbs to act on resources:

  • GET: Retrieves information from the resource.
  • PUT: Updates or replaces a resource.
  • POST: Creates a resource.
  • DETELE: Deletes a resource.
  • PATCH: Updates a specific characteristic or part of a resource.

Response Schema​

deepset REST API follows the OpenAPI schema standard. While core properties are consistently present in responses, some keys are optional and depend on your data and pipeline configuration. This is especially true for the answers[] and documents[] arrays. The answers[] array is always present in the Search endpoint response, but the meta objects within it may vary. For instance, they may contain a _references[] array in some responses, while being empty in others, depending on your content structure.

Always check if a property exists before accessing it and implement thorough data validation to make sure your code stays robust across different response structures.

Base URLs​

The base URL for Europe deployments is https://api.cloud.deepset.ai/ and for the US deployments is https://api.us.deepset.ai/. When testing endpoints in documentation, set the base URL to the deployment type you need.

All endpoints, except for Health, additionally use the api/v1/ prefix before the resource name, for example: https://api.cloud.deepset.ai/api/v1/users/.

Authentication​

Machine-to-machine authentication is done using an API key that you can generate in the deepset UI. Each API token is a Jason Web Token (JWT), a signed token whose signature can be verified using a key. For more information, see Generate an API Key.

The API key inherits the permissions of the user who created it. This means that if an Admin user creates an API key, the key has the same permissions as Admin.

Change management​

deepset policies regarding changes to the API, including the addition of new features, modifications to existing endpoints, and the deprecation process.

Changes to Endpoints​

Adding Fields​

deepset may add new fields to existing endpoints at any time without prior notice. These additions are not considered breaking changes. To ensure smooth operation, design your applications to handle unexpected fields gracefully.

Modifying or Removing Fields​

If we plan to modify or remove existing fields, we will:

  • Notify you through the newsletter.
  • Support both the old and new behaviors for at least two months before fully implementing the change.

New Endpoints​

New endpoints may be labeled as "beta." This means they may be unstable, and we don't recommend using them in your production scenarios until the label is removed.

Deprecation Policy​

When an endpoint is scheduled for removal, we will:

  • Mark it as deprecated in the documentation.
  • Announce the deprecation through the newsletter.
  • Maintain the deprecated endpoint for two months after the announcement date.

Stay Informed​

Subscribe to the newsletter for timely updates and review this documentation for the latest information.

Pagination, Timeouts, and Date-Time Format​

Pagination​

deepset API uses pagination to divide a large set of entities into separate pages, enhancing response times. Endpoints use either page-based or cursor-based pagination. Sometimes both options are possible but you can't use them at the same time.
When a request involves pagination, the API provides details about the total number of items available.

In page-based pagination, you specify the desired page and the number of items per page by using the page_number and limit query parameters. For example, to view 20 evaluation sets on page 2, your request would be as follows:

curl --request GET \
     --url 'https://api.cloud.deepset.ai/api/v1/workspaces/default/evaluation_sets?limit=20&page_number=2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <api_key>

To retrieve more files, make another request with updated pagination parameters. If you're using a script or app, iterate through the pages until you retrieve all the items or reach the desired number.

In cursor-based pagination, you can use the before or after parameter to view items preceding or following a specific item ID. For instance, to display 10 evaluation sets preceding the one with ID ab61f0cd-316a-4c66-879f-65dbe28ced1e, include this ID in the before parameter as shown below:

curl --request GET \
     --url 'https://api.cloud.deepset.ai/api/v1/workspaces/workspace_name/evaluation_sets?limit=10&before=ab61f0cd-316a-4c66-879f-65dbe28ced1e' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <api_key>

Date-Time​

All date-time values are in the UTC time in the ISO 8601 format, which follows the convention: YYYY-MM-DDTHH:MM:SS.sssZ, where:

  • YYYY is the year
  • MM is the month
  • DD is the day
  • T is the delimiter that separates the date from time
  • HH is the hour in a 24-hour clock format
  • MM is minutes
  • SS is seconds
  • .sss is fractional seconds, can be one or more digits, represent a decimal fraction of a second
  • Z is a suffix that indicates that the time is in UTC.

For example, 2023-04-25T07:37:58.326042Z represents 25th April 2023, 7:37 and 58.326042 seconds in UTC.

Timeouts​

The timeout for search is 2 minutes. The timeout for other requests is 3 minutes.

Status and Error Codes​

deepset API uses standard HTTP status codes. Here's a summary of the codes most often used.

Success Messages​

CodeMeaningPossible Reasons
200Successful response.Everything worked OK.
201Created.A resource was successfully created or added.
202Accepted.The request is accepted for processing but the processing is not yet finished.
204No content.The request was successfully processed and is not returning any content. One reason could be the successful deletion of a resource.

Client Errors​

CodeMeaningPossible Reasons
400Bad request.A missing required parameter or wrong syntax.
401Unauthorized.An invalid API key was provided.
403Forbidden.A missing or invalid API key.
404Not found.The resource doesn't exist.
406Not acceptable.The resource can only create content that is unacceptable in the response.
408Request timeout.The server waited too long for the request.
409Conflict.A resource already exists.
412Precondition failed.Check the details in the response. Possible reasons could be that deepset AI Platform is missing the required permissions to connect to the infrastructure, a resource is being used, a pipeline wasn't deployed.
413Payload too large.The data being uploaded exceeds the size limit. The size limit is 200 MB for files and 32766 bytes for metadata.
415Unsupported media type.deepset AI Platform doesn't support the format of the data being uploaded. For supported formats, see Upload Files.
422Content that cannot be processed.The request was correctly formed but couldn't be processed because of semantic errors.
424Failed dependency.The request failed because it depends on another request, which also failed.

Server Errors​

CodeMeaningPossible Reasons
500Internal server error.The server encountered a situation it doesn't know how to handle.
591Pipeline on standby.The pipeline wasn't used for a while and was put on standby to save resources. Wait a while until it's activated and try again.

You can check the full list of codes at MDN docs.

Resource IDs​

Some deepset API endpoints use resource IDs instead of names. For example, to list workspace integrations, you need the workspace ID. You can find IDs either by calling a REST API endpoint or by checking them in the UI.

Finding IDs in the UI​

You can copy all IDs directly from the platform interface.

Workspace ID​

  1. Click your profile icon.
  2. Go to Settings > Workspace > General.

Organization ID​

  1. Click your profile icon.
  2. Go to Settings > Organization > General.

Pipeline ID​

  1. Click Pipelines.
  2. Find the pipeline you need and click its name. This opens the Pipeline Details page, where the ID appears right below the pipeline name.

Index ID​

  1. Click Indexes.
  2. Find the index you need and click its name. This opens the Index Details page, where the ID appears right below the index name.

Job ID​

  1. Click Jobs.
  2. Find the job you need and click its name. This opens the Job Details page, where the ID appears right below the job name.

Finding IDs with API Endpoints​

Each resource type has a dedicated endpoint that returns its ID.