Search semantic model context

curl --request POST \
  --url https://{organization}.retrieval.credibledata.com/api/v1/get_context \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_targets": [
    {
      "search_text": "<string>"
    }
  ],
  "scopes": [
    {
      "environment": "<string>",
      "package": "<string>",
      "version": "<string>",
      "model_path": "<string>",
      "source": "<string>",
      "entity_name": "<string>"
    }
  ],
  "filter_params": {},
  "user_prompt": "<string>",
  "limit": 2,
  "offset": 1
}
'

import requests

url = "https://{organization}.retrieval.credibledata.com/api/v1/get_context"

payload = {
    "search_targets": [{ "search_text": "<string>" }],
    "scopes": [
        {
            "environment": "<string>",
            "package": "<string>",
            "version": "<string>",
            "model_path": "<string>",
            "source": "<string>",
            "entity_name": "<string>"
        }
    ],
    "filter_params": {},
    "user_prompt": "<string>",
    "limit": 2,
    "offset": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_targets: [{search_text: '<string>'}],
    scopes: [
      {
        environment: '<string>',
        package: '<string>',
        version: '<string>',
        model_path: '<string>',
        source: '<string>',
        entity_name: '<string>'
      }
    ],
    filter_params: {},
    user_prompt: '<string>',
    limit: 2,
    offset: 1
  })
};

fetch('https://{organization}.retrieval.credibledata.com/api/v1/get_context', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{organization}.retrieval.credibledata.com/api/v1/get_context",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_targets' => [
        [
                'search_text' => '<string>'
        ]
    ],
    'scopes' => [
        [
                'environment' => '<string>',
                'package' => '<string>',
                'version' => '<string>',
                'model_path' => '<string>',
                'source' => '<string>',
                'entity_name' => '<string>'
        ]
    ],
    'filter_params' => [
        
    ],
    'user_prompt' => '<string>',
    'limit' => 2,
    'offset' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{organization}.retrieval.credibledata.com/api/v1/get_context"

	payload := strings.NewReader("{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{organization}.retrieval.credibledata.com/api/v1/get_context")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{organization}.retrieval.credibledata.com/api/v1/get_context")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}"

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

{
  "sources": [
    {
      "source_info": {
        "resource_id": {
          "environment": "<string>",
          "package": "<string>",
          "version": "<string>",
          "model_path": "<string>",
          "source": "<string>",
          "entity_name": "<string>"
        },
        "docs": "<string>",
        "summary": "<string>",
        "filter_params": [
          {
            "name": "<string>",
            "dimension": "<string>",
            "required": true
          }
        ],
        "givens": [
          {
            "name": "<string>",
            "type": "<string>",
            "annotations": [
              "<string>"
            ],
            "default": "<string>"
          }
        ],
        "authorize": [
          {
            "expression": "<string>",
            "given_names": [
              "<string>"
            ]
          }
        ]
      },
      "relevance": 123,
      "prominence": 123,
      "matched_targets": [
        {
          "search_text": "<string>",
          "relevance": 123,
          "match_reason": "<string>"
        }
      ],
      "entities": [
        {
          "name": "<string>",
          "relevance": 123,
          "prominence": 123,
          "data_type": "<string>",
          "description": "<string>",
          "values": [
            {
              "value": "<string>",
              "relevance": 123,
              "prominence": 123,
              "search_text": "<string>"
            }
          ],
          "values_indexed": true,
          "code": "<string>",
          "matched_targets": [
            {
              "search_text": "<string>",
              "relevance": 123,
              "match_reason": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "total_available": 123,
  "returned": 123,
  "next_offset": 123,
  "warnings": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

retrieval

Search semantic model context

Search across published semantic models. Each search_targets entry picks an entity type (source, dimension, measure, view, or dimensional_value) with optional search_text; omitting search_text returns the most prominent items of that type. Results are sources with matched entities, ranked by relevance and prominence. Use scopes to narrow the search.

Response size budget (Max-Response-Chars header). Optionally send the Max-Response-Chars request header set to a positive integer to bound the serialized response size, in characters. When set, whole source cards are dropped from the end of the page so the response body stays within the budget; the paging envelope reports the reduced returned count and a warnings entry explains how to see the rest (page a listing, narrow a search). Cards are never truncated — only dropped whole — and at least one is always kept. This is a transport-level property of the caller’s channel — an MCP host rejects tool results above its context/token ceiling — rather than a query parameter, so it rides on a request header instead of the request body; the Credible MCP tools set it automatically. If the header is absent or not a positive integer it is ignored and the response is unbounded — a direct, non-MCP caller gets every ranked source.

POST

get_context

curl --request POST \
  --url https://{organization}.retrieval.credibledata.com/api/v1/get_context \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_targets": [
    {
      "search_text": "<string>"
    }
  ],
  "scopes": [
    {
      "environment": "<string>",
      "package": "<string>",
      "version": "<string>",
      "model_path": "<string>",
      "source": "<string>",
      "entity_name": "<string>"
    }
  ],
  "filter_params": {},
  "user_prompt": "<string>",
  "limit": 2,
  "offset": 1
}
'

import requests

url = "https://{organization}.retrieval.credibledata.com/api/v1/get_context"

payload = {
    "search_targets": [{ "search_text": "<string>" }],
    "scopes": [
        {
            "environment": "<string>",
            "package": "<string>",
            "version": "<string>",
            "model_path": "<string>",
            "source": "<string>",
            "entity_name": "<string>"
        }
    ],
    "filter_params": {},
    "user_prompt": "<string>",
    "limit": 2,
    "offset": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_targets: [{search_text: '<string>'}],
    scopes: [
      {
        environment: '<string>',
        package: '<string>',
        version: '<string>',
        model_path: '<string>',
        source: '<string>',
        entity_name: '<string>'
      }
    ],
    filter_params: {},
    user_prompt: '<string>',
    limit: 2,
    offset: 1
  })
};

fetch('https://{organization}.retrieval.credibledata.com/api/v1/get_context', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{organization}.retrieval.credibledata.com/api/v1/get_context",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_targets' => [
        [
                'search_text' => '<string>'
        ]
    ],
    'scopes' => [
        [
                'environment' => '<string>',
                'package' => '<string>',
                'version' => '<string>',
                'model_path' => '<string>',
                'source' => '<string>',
                'entity_name' => '<string>'
        ]
    ],
    'filter_params' => [
        
    ],
    'user_prompt' => '<string>',
    'limit' => 2,
    'offset' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{organization}.retrieval.credibledata.com/api/v1/get_context"

	payload := strings.NewReader("{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{organization}.retrieval.credibledata.com/api/v1/get_context")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{organization}.retrieval.credibledata.com/api/v1/get_context")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_targets\": [\n    {\n      \"search_text\": \"<string>\"\n    }\n  ],\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"package\": \"<string>\",\n      \"version\": \"<string>\",\n      \"model_path\": \"<string>\",\n      \"source\": \"<string>\",\n      \"entity_name\": \"<string>\"\n    }\n  ],\n  \"filter_params\": {},\n  \"user_prompt\": \"<string>\",\n  \"limit\": 2,\n  \"offset\": 1\n}"

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

{
  "sources": [
    {
      "source_info": {
        "resource_id": {
          "environment": "<string>",
          "package": "<string>",
          "version": "<string>",
          "model_path": "<string>",
          "source": "<string>",
          "entity_name": "<string>"
        },
        "docs": "<string>",
        "summary": "<string>",
        "filter_params": [
          {
            "name": "<string>",
            "dimension": "<string>",
            "required": true
          }
        ],
        "givens": [
          {
            "name": "<string>",
            "type": "<string>",
            "annotations": [
              "<string>"
            ],
            "default": "<string>"
          }
        ],
        "authorize": [
          {
            "expression": "<string>",
            "given_names": [
              "<string>"
            ]
          }
        ]
      },
      "relevance": 123,
      "prominence": 123,
      "matched_targets": [
        {
          "search_text": "<string>",
          "relevance": 123,
          "match_reason": "<string>"
        }
      ],
      "entities": [
        {
          "name": "<string>",
          "relevance": 123,
          "prominence": 123,
          "data_type": "<string>",
          "description": "<string>",
          "values": [
            {
              "value": "<string>",
              "relevance": 123,
              "prominence": 123,
              "search_text": "<string>"
            }
          ],
          "values_indexed": true,
          "code": "<string>",
          "matched_targets": [
            {
              "search_text": "<string>",
              "relevance": 123,
              "match_reason": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "total_available": 123,
  "returned": 123,
  "next_offset": 123,
  "warnings": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

{
  "message": "<string>",
  "details": "<string>"
}

Authorizations

Authorization

string

header

required

Auth0-issued user JWT. Provide as Authorization: Bearer <token>.

Body

application/json

Request body for the get_context endpoint

search_targets

object[]

required

Typed search targets describing what to find. Each target specifies a target type and optional search text for semantic matching.

Show child attributes

scopes

object[] | null

Optional list of scopes to narrow the search. Results will be scoped to the union of these.

Show child attributes

filter_params

object | null

Filter parameter values keyed by filter name. Used with sources that declare #(filter) annotations. Each value is either a single string or an array of strings (matches the dataplane API's filterParams shape). When the new dimensional-index path is enabled and active for a package whose target dimension declares #(filter, required), the corresponding filter values MUST be supplied here — the request will return 400 otherwise. Ignored on the legacy path.

user_prompt

string | null

Optional. The user's prompt that triggered this call, used for observability and downstream ranking. On the first turn this is the user's message verbatim. On follow-up turns where the user's message doesn't convey intent (e.g. "yes" to an agent suggestion), synthesize a short prompt that captures the intent of the turn. Use the same value for every get_context call within a single turn.

limit

integer | null

Maximum number of sources to return in this response (page size). PREFER OMITTING THIS: results are ranked, so the default page (20) already holds the best matches. When the caller supplies the Max-Response-Chars header (the MCP tools always do), the response is additionally bounded to that serialized size, so a page over the budget comes back with fewer sources (cards are unchanged, not stripped) plus a warning — a high limit does not guarantee more sources. A large total_available is a signal to narrow with search_text / scopes (or, on pure source listings, to page with offset), not to raise limit. Reserve explicit limits above 20 for genuine bulk enumeration. Values above 150 are clamped to 150; values below 1 are rejected with 400.

Required range: x >= 1

offset

integer | null

Number of sources to skip before the returned page, copied from a previous response's next_offset. Only meaningful on pure source-listing requests (only source targets, none with search_text) — listings have a deterministic order that can be resumed, while semantically ranked results do not. A non-zero offset alongside any search_text target or non-source target is rejected with 400; negative values are rejected with 400.

Required range: x >= 0

Response

Response from the get_context endpoint

sources

object[]

required

Matched sources sorted by relevance then prominence (empty when no good matches)

Show child attributes

ranking

enum<string> | null

How the returned sources were ordered. relevance when any search-text target contributed to the result set (semantic ranking); prominence for pure listings (deterministic usage/catalog order). Omitted when the request produced no result set (e.g. no search targets).

Available options:

relevance,

prominence

total_available

integer | null

Total number of distinct sources that matched or were in scope before the page cap was applied. When greater than returned, more sources exist than were included in this response — narrow with search_text / scopes, or (listings only) page with offset. Always populated by current servers; optional only so clients tolerate responses from servers predating this field.

returned

integer | null

Number of sources included in this response. Always populated by current servers; optional only so clients tolerate responses from servers predating this field.

next_offset

integer | null

The offset value that fetches the next page. Only present on pure source-listing responses when more sources remain past this page; pass it back via the request's offset field. Never present on semantically ranked (search) responses, which cannot be resumed — narrow the query instead.

warnings

string[] | null

Optional warnings about the result set (e.g. when results were truncated or capped). Omitted when empty.

Retrieval API Reference Search or enumerate indexed connection entities