Semantic search across folders

Performs semantic (vector) search across files in document folders. Returns the most relevant file chunks ranked by cosine similarity. Respects API key folder permissions.

POSThttps://api.deutschlandgpt.de/v2/document-folders/search

Example request

curl https://api.deutschlandgpt.de/v2/document-folders/search \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string",
  "folder_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "max_results": 10,
  "similarity_threshold": 0.3
}'

curl https://api.deutschlandgpt.de/v2/document-folders/search \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string",
  "folder_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "max_results": 10,
  "similarity_threshold": 0.3
}'

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/document-folders/search",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "query": "string",
        "folder_ids": [
            "00000000-0000-0000-0000-000000000000"
        ],
        "max_results": 10,
        "similarity_threshold": 0.3
    },
)

print(response.json())

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/document-folders/search",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "query": "string",
        "folder_ids": [
            "00000000-0000-0000-0000-000000000000"
        ],
        "max_results": 10,
        "similarity_threshold": 0.3
    },
)

print(response.json())

const response = await fetch('https://api.deutschlandgpt.de/v2/document-folders/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "query": "string",
    "folder_ids": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "max_results": 10,
    "similarity_threshold": 0.3
  }),
});

console.log(await response.json());

const response = await fetch('https://api.deutschlandgpt.de/v2/document-folders/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "query": "string",
    "folder_ids": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "max_results": 10,
    "similarity_threshold": 0.3
  }),
});

console.log(await response.json());

Request body

querystringrequired

Search query text

folder_idsstring<uuid>[]optional

Restrict search to specific folder IDs. Omit to search all accessible folders.

max_resultsintegeroptional

Maximum number of results

similarity_thresholdnumberoptional

Minimum cosine similarity score (0–1)

Response

200application/json

{
  "object": "list",
  "data": [
    {
      "file_id": "string",
      "file_name": "string",
      "file_type": "string",
      "folder_id": "00000000-0000-0000-0000-000000000000",
      "chunk_content": "string",
      "similarity_score": 0,
      "offset_start": 0,
      "offset_end": 0
    }
  ]
}

{
  "object": "list",
  "data": [
    {
      "file_id": "string",
      "file_name": "string",
      "file_type": "string",
      "folder_id": "00000000-0000-0000-0000-000000000000",
      "chunk_content": "string",
      "similarity_score": 0,
      "offset_start": 0,
      "offset_end": 0
    }
  ]
}

Search results

objectstring

dataSearchResult[]

file_idstring

file_namestring

file_typestring

folder_idstring<uuid>

chunk_contentstring

similarity_scorenumber

offset_startinteger

offset_endinteger

Response codes

200

Search results

object

401

Unauthorized

402

Insufficient credits or spending limit exceeded

Error

403

Requires enterprise workspace