Tutorial: Managing Feedback Entries Through REST API

Learn to add, update, and delete feedback entries using REST API endpoints.

  • Level: Basic
  • Time to complete: 10 minutes
  • Prerequisites:
    • You must have a basic understanding of REST API: HTTP methods, response and request structure, and basic concepts.
    • Basic programming knowledge is a plus.
    • You must have a deepset API key. For instructions, see Generate an API Key.
    • You must have a deepset pipeline and some files in your workspace. (You can use the sample files we provide). For help, see Create a Pipeline and Upload Files.
  • Goal: After completing this tutorial, you will know how to add, update, and delete feedback for your pipeline's answers using the REST API.

Get Pipeline and Workspace IDs

The feedback API uses workspace and pipeline IDs to identify them.

Get Pipeline ID

From the UI

  1. Click Pipelines.
  2. Find the pipeline whose ID you want to copy and click its name. This opens the Pipeline Details page. The ID is right below the pipeline name.

Using a REST API Endpoint

Use the Get Pipeline endpoint. You can use the following code snippet (cURL or Python). Fill in:

  • workspace name and pipeline name (in the URL).
  • your deepset API key (in headers).
import requests

url = "https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME>/pipelines/<YOUR_PIPELINE_NAME>"

headers = {
    "accept": "application/json",
    "authorization": "Bearer <DEEPSET_API_KEY>"
}

response = requests.get(url, headers=headers)

print(response.text)
curl --request GET \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME>/pipelines/<YOUR_PIPELINE_NAME> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <DEEPSET_API_KEY>'
Sample response
{
  "name": "RAG-QA-Llama3.1-405b",
  "pipeline_id": "07b04f1a-e053-4bd1-b3d5-e740b0dd6f2d", /* the pipeline ID*/
  "status": "DEPLOYED",
  "desired_status": "DEPLOYED",
  "created_at": "2024-12-09T11:35:38.218604Z",
  "deleted": false,
  "is_default": false,
  "created_by": {
    "given_name": "Jane",
    "family_name": "Smith",
    "user_id": "f6398740-5555-445d-8ae3-ef980ea4191d"
  },
  "last_edited_by": {
    "given_name": "Jane",
    "family_name": "Smith",
    "user_id": "f6398740-5555-445d-8ae3-ef980ea4191d"
  },
  "last_edited_at": "2024-12-09T11:35:44.219398Z",
  "supports_prompt": true,
  "output_type": "GENERATIVE",
  "last_deployed_at": "2024-12-09T11:39:34.767557Z",
  "service_level": "DEVELOPMENT",
  "idle_timeout_in_seconds": 43200,
  "deepset_cloud_version": "v2",
  "indexing": {
    "pending_file_count": 0,
    "failed_file_count": 0
  }
}

Get Workspace ID

From the UI

Click your profile icon and go to Settings>Workspace>General. Copy the ID from there.

Using a REST API Endpoint

Use the Get Workspace endpoint. You can also use the code sample below. Make sure you replace:

  • workspace name (in the URL).
  • your deepset API key (in headers
import requests

url = "https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME>"

headers = {
    "accept": "application/json",
    "authorization": "Bearer <DEEPSET_API_KEY>"
}

response = requests.get(url, headers=headers)

print(response.text)
curl --request GET \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <DEEPSET_API_KEY>'
Sample response
{
  "name": "legal-chat",
  "workspace_id": "b7f048eb-7b48-4ad8-b7b0-443cdddb81c5",
  "languages": {},
  "default_idle_timeout_in_seconds": 43200
}

Run a Search on Your Pipeline

Ask a query to get a response you can then give feedback on. Use the Search endpoint. You can use this code sample (cURL or Python) as a starting point. In the URL, replace:

  • YOUR_WORKSPACE_NAME with the name of the workspace containing the pipeline.
  • YOUR_PIPELINE_NAME with the name of the pipeline you want to run the search with.

In header, replace DEEPSET_API_KEY with your deepset API key.

import requests

url = "https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME>/pipelines/<YOUR_PIPELINE_NAME>/search"

payload = {
    "debug": False,
    "view_prompts": False,
    "queries": ["what are the symptomps of milk allegry?"]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer <DEEPSET_API_KEY>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
curl --request POST \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE_NAME>/pipelines/<YOUR_PIPELINE_NAME>/search \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <DEEPSET_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "debug": false,
  "view_prompts": false,
  "queries": [
    "what are the symptomps of milk allegry?"
  ]
}
'

The response contains the query and the result ID, which you'll need to add, update, or delete feedback entries.

ℹ️

Finding the Correct Result and Query IDs

To add a feedback entry, you'll need the result ID associated with the answer. In the example response below, the result ID is 7e07bd73-c099-44fe-9d65-ec0ba5e83c41.

Keep in mind that each document also has its own result ID. Make sure to use the result ID from the answer itself when adding your feedback.

For the query ID, make sure to use the query ID located in the results object. In the example below, it's 37547edb-48ec-49c0-96e8-1fcb5f37bd0c.

Sample response
{
  "query_id": "example-query-id",
  "results": [
    {
      "query": "Example query",
      "answers": [
        {
          "answer": "Sample answer",
          "type": "generative"
        }
      ]
    }
  ]
}