Skip to main content
POST
/
v1
/
tools
/
semantic-search
Semantic Search
curl --request POST \
  --url https://{base_url}/gpt/v1/tools/semantic-search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "context_filter": {
    "collection": "pgpt_collection",
    "artifacts": [
      "artifact_id_1, artifact_id_2"
    ],
    "metadata_filter": [
      {
        "key": "file_id",
        "operator": "==",
        "value": "artifact_id_1"
      }
    ]
  }
}
'
{
  "content": [
    {
      "type": "source",
      "sources": [
        {
          "object": "context.chunk",
          "id": "d3ab07fe-b7ab-4fda-8524-1cb41b01200a",
          "score": 0.83,
          "document": {
            "object": "ingest.document",
            "artifact": "0196ee69-666a-7bcd-800b-b01fa9b2f24c",
            "doc_metadata": {
              "file_name": "dense_x_retrieval.pdf"
            }
          },
          "text": "Wenhao Yu et al. 2023. Chain-ofnote: Enhancing robustness in retrieval-augmented LMs.",
          "content_type": "text/markdown",
          "metadata": {
            "page": 13,
            "shorter_id": "GONG"
          },
          "previous_texts": [],
          "next_texts": []
        }
      ]
    },
    {
      "type": "text",
      "text": "**Context Information**:\nCitation identifier [GONG]\n---\nContent:\nWenhao Yu, Hongming Zhang... Chain-ofnote: Enhancing robustness in retrieval-augmented language models."
    }
  ],
  "is_error": false
}

Body

application/json

Request body for semantic search. Includes the query, optional filters, and response formatting preferences.

Request body for semantic search.

​
query
string
required

The natural language query to search for relevant content.

Example:

"What were the Q4 revenue trends?"

​
context_filter
ContextFilter · object
required

Filters to narrow the search context (collections, artifacts, metadata).

​
format
enum<string>
default:default

Format of the result content. 'default' returns standard content blocks. 'citations' returns blocks annotated for citation formatting.

Available options:
default,
citations
Example:

"default"

Response

Semantic search completed successfully.

Response returned from tool-based operations.

​
content
(TextBlock · object | ImageBlock · object | AudioBlock · object | BinaryBlock · object | ResourceLinkBlock · object | ResourceBlock · object | SourceBlock · object | ToolUseBlock · object | ThinkingBlock · object | TLDRBlock · object)[]
required

List of content blocks generated by the tool. Blocks can include plain text, citations, source attributions, or images.

Text content block containing natural language text.

​
is_error
boolean
default:false

True if the tool encountered an error during execution.