> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.privategpt.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server.

# Semantic Search

POST /v1/tools/semantic-search
Content-Type: application/json

Run a semantic search using natural language and contextual filters. Supports citation formatting.

Reference: https://docs.privategpt.dev/api-reference/tools/semantic-search-v-1-tools-semantic-search-post

## Request

### Body (application/json)

This endpoint expects a SemanticSearchBody.

- `query` (string, required) — The natural language query to search for relevant content.
- `context_filter` (ContextFilter, required) — Filters to narrow the search context (collections, artifacts, metadata).
- `format` (enum, optional, default: default) — Format of the result content. 'default' returns standard content blocks. 'citations' returns blocks annotated for citation formatting.
  - Allowed values: `default`, `citations`

## Response

### 200

Semantic search completed successfully.

- `content` (list of ToolResponseContentItems, required) — List of content blocks generated by the tool. Blocks can include plain text, citations, source attributions, or images.
- `is_error` (boolean, optional, default: false) — True if the tool encountered an error during execution.

## Errors

### 401 Unauthorized Error

Unauthorized

- `any`

### 422 Unprocessable Entity Error

Validation Error - Invalid request parameters

- `detail` (OpenApiValidationErrorResponseDetail, required) — Error detail — a string message or a list of validation error objects.

## Types

### ContextFilter

Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters.

- `collection` (string, optional, default: pgpt_collection) — The name of the collection to filter on.
- `artifacts` (list of string, optional, nullable) — Artifacts ids to filter on.
- `metadata_filter` (list of map from string to any, optional, nullable) — Metadata filter to apply on the context.

### ToolResponseContentItems

### OpenApiValidationErrorResponseDetail

Error detail — a string message or a list of validation error objects.

### TextBlock

Plain-text content block.

- `type` ("text", required) — type field.
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (TextBlockCacheControl, optional, nullable) — cache control field.
- `text` (string, optional, default: ) — Text payload for this block.
- `citations` (list of ZylonCitation, optional, nullable, default: []) — citations field.

### ImageBlock

Anthropic-compatible image content block.

- `type` ("image", required) — type field.
- `source` (ImageBlockSource, required) — Anthropic image source payload
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (ImageBlockCacheControl, optional, nullable) — cache control field.

### AudioBlock

Anthropic-compatible audio content block.

- `type` ("audio", required) — type field.
- `source` (AudioBlockSource, required) — Audio source payload
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (AudioBlockCacheControl, optional, nullable) — cache control field.

### BinaryBlock

Arbitrary binary payload (PDF, ZIP, …) encoded as base64.

- `type` ("binary", required) — type field.
- `source` (BinaryBlockSource, required) — Binary source payload
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `filename` (string, optional, nullable) — filename field.

### LocalResourceBlock

Reference to a local file produced by code execution.

- `type` ("local_resource", required) — type field.
- `file_path` (string, required) — Absolute path to the file inside the execution environment
- `name` (string, required) — Human-readable file name (stem, without extension)
- `mime_type` (string, required) — MIME type of the file
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `file_id` (string, optional, nullable) — Base64url-encoded storage file ID used to download the file via the files API

### ResourceLinkBlock

Reference to an external resource by URI (not embedded).

- `type` ("resource_link", required) — type field.
- `uri` (string, required) — URI of the external resource
- `name` (string, required) — Human-readable resource name
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `description` (string, optional, nullable) — description field.
- `mime_type` (string, optional, nullable) — mime type field.

### ResourceBlock

Embedded resource with metadata.

- `type` ("resource", required) — type field.
- `resource` (Resource, required) — Embedded resource metadata
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.

### SourceBlock

Document chunks surfaced as RAG context attribution.

- `type` ("source", required) — type field.
- `sources` (list of SourceBlockSourcesItems, required) — Document chunks used as context for this response
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.

### ThinkingBlock

Extended thinking block containing the model's reasoning process.

- `type` ("thinking", required) — type field.
- `signature` (string, required) — Anthropic reasoning signature required for extended thinking compatibility
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (ThinkingBlockCacheControl, optional, nullable) — cache control field.
- `thinking` (string, optional, default: ) — Thinking payload
- `citations` (list of ZylonCitation, optional, nullable, default: []) — citations field.

### RedactedThinkingBlock

Redacted thinking block returned when thinking content is encrypted.

- `type` ("redacted_thinking", required) — type field.
- `data` (string, required) — Encrypted thinking payload
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (RedactedThinkingBlockCacheControl, optional, nullable) — cache control field.

### ToolUseBlock

Represents a model-initiated tool call.

- `type` ("tool_use", required) — type field.
- `id` (string, required) — Unique identifier for this tool use
- `name` (string, required) — Name of the tool being called
- `input` (map from string to any, required) — Input payload for the tool call
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (ToolUseBlockCacheControl, optional, nullable) — cache control field.
- `caller` (ToolUseBlockCaller, optional, nullable) — caller field.

### ServerToolUseBlock

Represents a server-side (built-in) tool call initiated by the model.

- `type` ("server_tool_use", required) — type field.
- `id` (string, required) — Unique identifier for this server tool use
- `name` (enum, required) — Name of the server tool being called
  - Allowed values: `web_search`, `web_fetch`, `code_execution`, `bash_code_execution`, `text_editor_code_execution`, `tool_search_tool_regex`, `tool_search_tool_bm25`
- `input` (map from string to any, required) — Input payload for the server tool call
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (ServerToolUseBlockCacheControl, optional, nullable) — cache control field.
- `caller` (ServerToolUseBlockCaller, optional, nullable) — caller field.

### ContainerUploadBlock

References a file that was uploaded to an Anthropic container.

- `type` ("container_upload", required) — type field.
- `file_id` (string, required) — Container file identifier
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (ContainerUploadBlockCacheControl, optional, nullable) — cache control field.

### DocumentBlock

Anthropic document block (used for document-grounded generation).

- `type` ("document", required) — type field.
- `source` (DocumentBlockSource, required) — Document source payload
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (DocumentBlockCacheControl, optional, nullable) — cache control field.
- `title` (string, optional, nullable) — title field.
- `context` (string, optional, nullable) — context field.
- `citations` (list of ZylonCitation, optional, nullable) — citations field.

### SearchResultBlock

Anthropic search result block.

- `type` ("search_result", required) — type field.
- `source` (string, required) — Search result source payload
- `title` (string, required) — Search result title
- `content` (list of TextBlock, required) — Search result content
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (SearchResultBlockCacheControl, optional, nullable) — cache control field.
- `citations` (list of ZylonCitation, optional, nullable) — citations field.

### MidConvSystemBlock

System instructions injected at a specific point mid-conversation.

- `type` ("mid_conv_system", required) — type field.
- `content` (list of TextBlock, required) — System instruction text blocks.
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `cache_control` (MidConvSystemBlockCacheControl, optional, nullable) — cache control field.

### TLDRBlock

Condensed summary block.

- `type` ("tldr", required) — type field.
- `start_timestamp` (datetime, optional, nullable) — start timestamp field.
- `stop_timestamp` (datetime, optional, nullable) — stop timestamp field.
- `_meta` (map from string to any, optional) — meta field.
- `content` (list of TldrBlockContentItems, optional) — content field.
- `tldr_side` (enum, optional, default: left) — tldr side field.
  - Allowed values: `left`, `right`

### TextBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### ZylonCitation

ZylonCitation represents a citation in the Zylon format.

- `id` (string, optional, nullable) — Unique identifier for the citation
- `index` (integer, optional, nullable) — Index of the citation in the document
- `artifact_id` (string, optional, nullable) — Identifier of the artifact associated with the citation
- `source_id` (string, optional, nullable) — Identifier of the source document from which the citation is derived

### ImageBlockSource

Anthropic image source payload

- `type`: `base64` (Base64ImageSource)
  - `data` (string, required) — Base64-encoded image bytes
  - `media_type` (enum, required) — media type field.
    - Allowed values: `image/jpeg`, `image/png`, `image/gif`, `image/webp`
- `type`: `url` (URLSource)
  - `url` (string, required) — Publicly reachable URL

### ImageBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### AudioBlockSource

Audio source payload

- `type`: `base64` (Base64AudioSource)
  - `data` (string, required) — Base64-encoded audio bytes
  - `media_type` (string, required) — Audio MIME type, e.g. 'audio/mpeg'
- `type`: `url` (URLSource)
  - `url` (string, required) — Publicly reachable URL

### AudioBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### BinaryBlockSource

Binary source payload

- `type`: `base64` (Base64BinarySource)
  - `data` (string, required) — Base64-encoded binary data
  - `media_type` (string, required) — MIME type, e.g. 'application/pdf'
- `type`: `url` (url)

### Resource

Resource schema.

- `uri` (string, required) — uri field.
- `name` (string, required) — name field.
- `description` (string, optional, nullable) — description field.
- `mime_type` (string, optional, nullable) — mime type field.

### SourceBlockSourcesItems

### ThinkingBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### RedactedThinkingBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### ToolUseBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### ToolUseBlockCaller

caller field.

- `type`: `code_execution_20250825` (ServerToolCaller)
  - `tool_id` (string, required) — Server tool identifier.
- `type`: `code_execution_20260120` (ServerToolCaller20260120)
  - `tool_id` (string, required) — Server tool identifier.
- `type`: `direct` (DirectCaller)

### ServerToolUseBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### ServerToolUseBlockCaller

caller field.

- `type`: `code_execution_20250825` (ServerToolCaller)
  - `tool_id` (string, required) — Server tool identifier.
- `type`: `code_execution_20260120` (ServerToolCaller20260120)
  - `tool_id` (string, required) — Server tool identifier.
- `type`: `direct` (DirectCaller)

### ContainerUploadBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### DocumentBlockSource

Document source payload

- `type`: `base64` (Base64Source)
  - `data` (string, required) — data field.
  - `media_type` (string, required) — media type field.
- `type`: `content` (content)
- `type`: `text` (PlainTextSource)
  - `data` (string, required) — data field.
  - `media_type` ("text/plain", required) — media type field.
- `type`: `url` (URLDocumentSource)
  - `url` (string, required) — url field.

### DocumentBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### SearchResultBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### MidConvSystemBlockCacheControl

cache control field.

- `type`: `ephemeral` (CacheControlEphemeral)
  - `ttl` (enum, optional, default: 5m) — ttl field.
    - Allowed values: `5m`, `1h`

### TldrBlockContentItems

### Chunk

Represents a chunk of text content from an ingested document.

- `object` ("context.chunk", required) — Object type identifier, always 'context.chunk' for chunk responses
- `score` (double, required) — Relevance score indicating how well this chunk matches the query (0.0 to 1.0, higher is better)
- `document` (IngestedDoc, required) — Reference to the parent document containing metadata and ingestion information
- `text` (string, required) — The actual text content of the chunk extracted from the document
- `id` (string, optional, nullable) — Unique identifier for the chunk within the document
- `content_type` (string, optional, default: text/plain) — MIME type indicating the format of the chunk content
- `previous_texts` (list of string, optional, nullable) — List of text chunks that appear before this chunk in the document, providing preceding context
- `next_texts` (list of string, optional, nullable) — List of text chunks that appear after this chunk in the document, providing following context
- `metadata` (map from string to any, optional, nullable) — Additional metadata about the chunk including positioning information and document properties

### Website

Represents a website URL source.

- `id` (string, required) — Unique identifier for the website source
- `object` ("context.website", required) — Object type identifier, always 'context.website' for website sources
- `url` (string, required) — The URL of the website
- `favicon_url` (string, optional, nullable) — The URL of the website's favicon
- `title` (string, optional, nullable) — The title of the website or webpage
- `description` (string, optional, nullable) — A brief description or summary of the website content
- `metadata` (map from string to any, optional, nullable) — Additional metadata about the website source
- `content_type` (string, optional, nullable) — MIME type indicating the format of the website content
- `content` (string, optional, nullable) — The actual text content extracted from the website

### IngestedDoc

Represents a document that has been ingested into the system.

- `artifact` (string, required) — Unique identifier for the ingested document artifact.
- `object` ("ingest.document", optional, default: ingest.document) — Type of the object, indicating this is an ingested document.
- `doc_metadata` (map from string to any, optional, nullable) — Metadata associated with the ingested document, such as title, author, and other

## Examples

**Request**

```json
{
  "query": "What were the Q4 revenue trends?"
}
```

**Response**

```json
{
  "content": [
    {
      "sources": [
        {
          "content_type": "text/markdown",
          "document": {
            "artifact": "0196ee69-666a-7bcd-800b-b01fa9b2f24c",
            "doc_metadata": {
              "file_name": "dense_x_retrieval.pdf"
            },
            "object": "ingest.document"
          },
          "id": "d3ab07fe-b7ab-4fda-8524-1cb41b01200a",
          "metadata": {
            "page": 13,
            "shorter_id": "GONG"
          },
          "next_texts": [],
          "object": "context.chunk",
          "previous_texts": [],
          "score": 0.83,
          "text": "Wenhao Yu et al. 2023. Chain-ofnote: Enhancing robustness in retrieval-augmented LMs."
        }
      ],
      "type": "source"
    },
    {
      "text": "**Context Information**:\nCitation identifier [GONG]\n---\nContent:\nWenhao Yu, Hongming Zhang... Chain-ofnote: Enhancing robustness in retrieval-augmented language models.",
      "type": "text"
    }
  ],
  "is_error": false
}
```

**SDK Code**

```python Search result with sources
import requests

url = "https://api.example.com/v1/tools/semantic-search"

payload = { "query": "What were the Q4 revenue trends?" }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript Search result with sources
const url = 'https://api.example.com/v1/tools/semantic-search';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"query":"What were the Q4 revenue trends?"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search result with sources
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/tools/semantic-search"

	payload := strings.NewReader("{\n  \"query\": \"What were the Q4 revenue trends?\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search result with sources
require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/tools/semantic-search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"What were the Q4 revenue trends?\"\n}"

response = http.request(request)
puts response.read_body
```

```java Search result with sources
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/tools/semantic-search")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"What were the Q4 revenue trends?\"\n}")
  .asString();
```

```php Search result with sources
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/v1/tools/semantic-search', [
  'body' => '{
  "query": "What were the Q4 revenue trends?"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Search result with sources
using RestSharp;

var client = new RestClient("https://api.example.com/v1/tools/semantic-search");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": \"What were the Q4 revenue trends?\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search result with sources
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["query": "What were the Q4 revenue trends?"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/tools/semantic-search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```