Corpus Semantic Similarity - Retrieve API

The Corpus Retrieve API allows you to perform a semantic similarity search over a Corpus within a Project in Glob.AI OS and returns the most relevant document chunks for a natural-language query.

It embeds the query, searches the corpus vector store, optionally applies metadata filters and a reranker, and returns ranked chunks with their similarity scores and source metadata.

To let an Agent use the corpus as a Tool during a chat, see Agent Usage.

For generic variables needed to use the API, see the API Reference.

All endpoints on this page require project-scoped access to the target Corpus's Organization/Project.

Endpoints

Authentication

All endpoints require authentication using one of the following:

• Authorization: Bearer $GEAI_APITOKEN
• Authorization: Bearer $OAuth_accesstoken

For $OAuth_accesstoken, you must also include the headers:

• project-id: $GEAI_PROJECT_ID
• organization-id: $GEAI_ORGANIZATIONID

Some endpoints may require additional headers such as:

• Content-Type: application/json
• Accept: application/json

When using a Project API Token, the Project and Organization are implicit and the project-id and organization-id headers can be omitted.

POST /v1/corpus/{CorpusId}/retrieve

Search a corpus using a natural-language query and return its most relevant document chunks.

Parameters

Request

• Method: POST
• Path: $BASE_URL/v1/corpus/{CorpusId}/retrieve

Request Body

{
  "query": "anything on subject?", // required, string — natural-language query to match against the corpus
  "scoreThreshold": 0.1, // optional, number — minimum similarity score for a chunk to be returned; range: 0 to 1
  "topK": 3, // optional, integer — maximum number of chunks to return; positive integer
  "filters": [ // optional, array — metadata filters; multiple filters are combined with AND
    {
      "key": "extension", // string — metadata field name, e.g. "extension", "name", or a custom metadata key set at upload time
      "operator": "$eq", // string — comparison operator; observed: "$eq" | "$ne"; the contract also references "gt", "lt", etc.
      "value": "txt" // string | array — value to match
    }
  ],
  "rerank": { // optional, object — reranking options
    "provider": "cohere", // string — reranking provider
    "modelName": "rerank-v3.5", // string — reranking model name
    "relevanceScore": 0.015, // number — reranker relevance-score threshold
    "k": 2 // integer — number of results retained after reranking
  }
}

Only query is required. All other fields are optional and fall back to corpus or backend defaults.

Response

Returns matching chunks in resources, each with pageContent, a score, and source metadata.

{
  "resources": [
    {
      "pageContent": "some text…", // string — chunk text
      "score": 0.89, // number — similarity score; higher values indicate a closer match
      "metadata": {
        "id": "GUID", // string (uuid) — source document id
        "name": "name", // string — source document name
        "description": "description", // string — source document description
        "extension": "txt", // string — source document extension
        "source": "$BASE_URL/v1/document/GUID", // string — URL to the source document
        "loc": {
          "pageNumber": 1 // integer — location within the document; the API may alternatively return lines with from and to
        }
      }
    }
  ],
  "success": true, // boolean — overall success flag
  "result": {
    "success": true // boolean — present in some responses
  },
  "error": {} // object — error details; often empty on success
}

cURL Sample

curl -X POST "$BASE_URL/v1/corpus/{CorpusId}/retrieve" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anything on subject?"
  }'

curl -X POST "$BASE_URL/v1/corpus/{CorpusId}/retrieve" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anything on subject?",
    "scoreThreshold": 0.1,
    "topK": 3,
    "filters": [
      { "key": "extension", "operator": "$eq", "value": "txt" }
    ]
  }'

curl -X POST "$BASE_URL/v1/corpus/{CorpusId}/retrieve" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anything on subject?",
    "rerank": {
      "provider": "cohere",
      "modelName": "rerank-v3.5",
      "relevanceScore": 0.015,
      "k": 2
    },
    "filters": [
      {
        "key": "extension",
        "operator": "$eq",
        "value": "txt"
      }
    ],
    "scoreThreshold": 0.1,
    "topK": 3
  }'

Availability

Since version 2026-06.