This guide's goal is to give you all the necessary information to effectively interact with our API. Learn about the authentication, base URL, and basic organization of the API.
deepset Cloud API
deepset Cloud 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
Our 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 URL
The base URL is https://api.cloud.deepset.ai/.
All endpoints, except for Redirect and 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 Cloud 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.
Private Endpoints
Some endpoints are marked as [private]. The schema for these endpoints may change, which means the structure, format, or data exchanged at those endpoints may change over time.
For all other endpoints, we maintain the same schema.