Search or enumerate indexed connection entities

curl --request POST \
  --url https://{organization}.retrieval.credibledata.com/api/v1/search_connection_entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scopes": [
    {
      "environment": "<string>",
      "connection_name": "<string>",
      "catalog_name": "<string>",
      "schema_name": "<string>",
      "table_name": "<string>"
    }
  ],
  "query": "<string>",
  "entity_types": [],
  "origin_types": [],
  "include_joined_entities": false,
  "min_score": 123,
  "top_n_results": 123,
  "max_entities_per_result": 123,
  "max_dimensional_values": 123,
  "limit": 2,
  "offset": 1
}
'

import requests

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

payload = {
    "scopes": [
        {
            "environment": "<string>",
            "connection_name": "<string>",
            "catalog_name": "<string>",
            "schema_name": "<string>",
            "table_name": "<string>"
        }
    ],
    "query": "<string>",
    "entity_types": [],
    "origin_types": [],
    "include_joined_entities": False,
    "min_score": 123,
    "top_n_results": 123,
    "max_entities_per_result": 123,
    "max_dimensional_values": 123,
    "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({
    scopes: [
      {
        environment: '<string>',
        connection_name: '<string>',
        catalog_name: '<string>',
        schema_name: '<string>',
        table_name: '<string>'
      }
    ],
    query: '<string>',
    entity_types: [],
    origin_types: [],
    include_joined_entities: false,
    min_score: 123,
    top_n_results: 123,
    max_entities_per_result: 123,
    max_dimensional_values: 123,
    limit: 2,
    offset: 1
  })
};

fetch('https://{organization}.retrieval.credibledata.com/api/v1/search_connection_entities', 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/search_connection_entities",
  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([
    'scopes' => [
        [
                'environment' => '<string>',
                'connection_name' => '<string>',
                'catalog_name' => '<string>',
                'schema_name' => '<string>',
                'table_name' => '<string>'
        ]
    ],
    'query' => '<string>',
    'entity_types' => [
        
    ],
    'origin_types' => [
        
    ],
    'include_joined_entities' => false,
    'min_score' => 123,
    'top_n_results' => 123,
    'max_entities_per_result' => 123,
    'max_dimensional_values' => 123,
    '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/search_connection_entities"

	payload := strings.NewReader("{\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\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/search_connection_entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\n  \"limit\": 2,\n  \"offset\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\n  \"limit\": 2,\n  \"offset\": 1\n}"

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

[
  {
    "package_info": {
      "organization": "<string>",
      "project": "<string>",
      "package": "<string>",
      "version": "<string>"
    },
    "model_uri": "<string>",
    "source": "<string>",
    "source_docs": "<string>",
    "score": 123,
    "matches": [
      {
        "id": "<string>",
        "phrase": "<string>",
        "phrase_extended": "<string>",
        "phrase_type": "<string>",
        "phrase_dim_value_strings": [
          "<string>"
        ],
        "score": 123,
        "entities": [
          {
            "entity": {
              "name": "<string>",
              "field_type": "<string>",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "field_data_type": "<string>",
              "is_malloy": true,
              "source": "<string>",
              "code": "<string>",
              "tags": "<string>",
              "uri": "<string>",
              "origin_type": "<string>",
              "join_path": "<string>",
              "description": "<string>",
              "keyphrase": "<string>",
              "name_readable": "<string>",
              "frequency": 123,
              "table_info": {
                "table_id": "<string>",
                "connection_name": "<string>",
                "catalog_name": "<string>",
                "schema_name": "<string>",
                "table_name": "<string>"
              },
              "join_info": {
                "join_table_id": "<string>",
                "join_table_catalog": "<string>",
                "join_table_schema": "<string>",
                "join_table_name": "<string>",
                "primary_table_field": "<string>",
                "join_table_field": "<string>"
              },
              "join_source_metadata": {
                "original_source_name": "<string>",
                "original_source_path": "<string>",
                "is_nested_index": true
              },
              "dim_index_fingerprint": {
                "sql_fingerprint": "<string>",
                "required_filter_dimensions": [
                  "<string>"
                ]
              },
              "index_policy": {
                "freshness": {
                  "window": "<string>"
                }
              }
            },
            "package_info": {
              "organization": "<string>",
              "project": "<string>",
              "package": "<string>",
              "version": "<string>"
            },
            "match_score": 123,
            "match_reason": "<string>",
            "dimensional_value_matches": [
              {
                "value": "<string>",
                "match_string": "<string>",
                "score": 123,
                "frequency": 123
              }
            ]
          }
        ]
      }
    ]
  }
]

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

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

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

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

retrieval

Search or enumerate indexed connection entities

Search for (or, with skip_matching, enumerate) connection-scoped entities in the connection index (tables, columns, and modeling suggestions). Results are always grouped by table. Powers the Credible app’s connection schema viewer and the MCP search_database_schema / search_modeling_suggestions tools. Package-scoped retrieval has moved to get_context. Results are scoped to what the caller can access (OpenFGA scoped-access checks).

Paging (enumerate path only). When limit is set on the request, the enumerate path (no query) returns at most that many distinct tables in a stable order and reports the total number of in-scope tables on the Total-Count response header; page forward with offset. The response body is unchanged — a bare RetrievalResult array — so existing callers that ignore the header and omit limit are unaffected.

POST

search_connection_entities

curl --request POST \
  --url https://{organization}.retrieval.credibledata.com/api/v1/search_connection_entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scopes": [
    {
      "environment": "<string>",
      "connection_name": "<string>",
      "catalog_name": "<string>",
      "schema_name": "<string>",
      "table_name": "<string>"
    }
  ],
  "query": "<string>",
  "entity_types": [],
  "origin_types": [],
  "include_joined_entities": false,
  "min_score": 123,
  "top_n_results": 123,
  "max_entities_per_result": 123,
  "max_dimensional_values": 123,
  "limit": 2,
  "offset": 1
}
'

import requests

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

payload = {
    "scopes": [
        {
            "environment": "<string>",
            "connection_name": "<string>",
            "catalog_name": "<string>",
            "schema_name": "<string>",
            "table_name": "<string>"
        }
    ],
    "query": "<string>",
    "entity_types": [],
    "origin_types": [],
    "include_joined_entities": False,
    "min_score": 123,
    "top_n_results": 123,
    "max_entities_per_result": 123,
    "max_dimensional_values": 123,
    "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({
    scopes: [
      {
        environment: '<string>',
        connection_name: '<string>',
        catalog_name: '<string>',
        schema_name: '<string>',
        table_name: '<string>'
      }
    ],
    query: '<string>',
    entity_types: [],
    origin_types: [],
    include_joined_entities: false,
    min_score: 123,
    top_n_results: 123,
    max_entities_per_result: 123,
    max_dimensional_values: 123,
    limit: 2,
    offset: 1
  })
};

fetch('https://{organization}.retrieval.credibledata.com/api/v1/search_connection_entities', 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/search_connection_entities",
  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([
    'scopes' => [
        [
                'environment' => '<string>',
                'connection_name' => '<string>',
                'catalog_name' => '<string>',
                'schema_name' => '<string>',
                'table_name' => '<string>'
        ]
    ],
    'query' => '<string>',
    'entity_types' => [
        
    ],
    'origin_types' => [
        
    ],
    'include_joined_entities' => false,
    'min_score' => 123,
    'top_n_results' => 123,
    'max_entities_per_result' => 123,
    'max_dimensional_values' => 123,
    '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/search_connection_entities"

	payload := strings.NewReader("{\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\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/search_connection_entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\n  \"limit\": 2,\n  \"offset\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"scopes\": [\n    {\n      \"environment\": \"<string>\",\n      \"connection_name\": \"<string>\",\n      \"catalog_name\": \"<string>\",\n      \"schema_name\": \"<string>\",\n      \"table_name\": \"<string>\"\n    }\n  ],\n  \"query\": \"<string>\",\n  \"entity_types\": [],\n  \"origin_types\": [],\n  \"include_joined_entities\": false,\n  \"min_score\": 123,\n  \"top_n_results\": 123,\n  \"max_entities_per_result\": 123,\n  \"max_dimensional_values\": 123,\n  \"limit\": 2,\n  \"offset\": 1\n}"

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

[
  {
    "package_info": {
      "organization": "<string>",
      "project": "<string>",
      "package": "<string>",
      "version": "<string>"
    },
    "model_uri": "<string>",
    "source": "<string>",
    "source_docs": "<string>",
    "score": 123,
    "matches": [
      {
        "id": "<string>",
        "phrase": "<string>",
        "phrase_extended": "<string>",
        "phrase_type": "<string>",
        "phrase_dim_value_strings": [
          "<string>"
        ],
        "score": 123,
        "entities": [
          {
            "entity": {
              "name": "<string>",
              "field_type": "<string>",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "field_data_type": "<string>",
              "is_malloy": true,
              "source": "<string>",
              "code": "<string>",
              "tags": "<string>",
              "uri": "<string>",
              "origin_type": "<string>",
              "join_path": "<string>",
              "description": "<string>",
              "keyphrase": "<string>",
              "name_readable": "<string>",
              "frequency": 123,
              "table_info": {
                "table_id": "<string>",
                "connection_name": "<string>",
                "catalog_name": "<string>",
                "schema_name": "<string>",
                "table_name": "<string>"
              },
              "join_info": {
                "join_table_id": "<string>",
                "join_table_catalog": "<string>",
                "join_table_schema": "<string>",
                "join_table_name": "<string>",
                "primary_table_field": "<string>",
                "join_table_field": "<string>"
              },
              "join_source_metadata": {
                "original_source_name": "<string>",
                "original_source_path": "<string>",
                "is_nested_index": true
              },
              "dim_index_fingerprint": {
                "sql_fingerprint": "<string>",
                "required_filter_dimensions": [
                  "<string>"
                ]
              },
              "index_policy": {
                "freshness": {
                  "window": "<string>"
                }
              }
            },
            "package_info": {
              "organization": "<string>",
              "project": "<string>",
              "package": "<string>",
              "version": "<string>"
            },
            "match_score": 123,
            "match_reason": "<string>",
            "dimensional_value_matches": [
              {
                "value": "<string>",
                "match_string": "<string>",
                "score": 123,
                "frequency": 123
              }
            ]
          }
        ]
      }
    ]
  }
]

{
  "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 search_connection_entities endpoint. Self-contained and scoped to the connection index — it does not reference the broader internal retrieval context. Results are always grouped by table.

scopes

object[]

required

Connection scopes to search within. Results are restricted to the union of these scopes, further intersected with what the caller can access. At least one scope is required.

Minimum array length: 1

Show child attributes

query

string | null

Natural-language text to semantically match against indexed entities. When null or empty, the endpoint enumerates every indexed entity in scope (no semantic matching) — used by callers that just want to list the contents of a connection.

entity_types

enum<string>[] | null

Restrict results to these entity types. When omitted, all types are returned.

The type of connection-index entity to search for. all is a convenience marker that matches every concrete type.

Available options:

all,

table,

column,

dimension,

measure,

view,

join,

dimensional_value

origin_types

enum<string>[] | null

Restrict results to entities of these origins. When omitted, all origins are returned.

The origin of a connection-index entity. all is a convenience marker that matches every origin.

Available options:

all,

published,

sql_logs,

llm_generated

include_joined_entities

boolean | null

default:false

When true, also include entities reachable from the scoped tables via joins. Defaults to false.

min_score

number | null

Minimum cosine-similarity score for a semantic match (ignored when enumerating). Defaults to 0.

top_n_results

integer | null

Maximum number of table-grouped results to return. Omit for the service default; a value <= 0 returns every matching table.

max_entities_per_result

integer | null

Maximum number of entities to return per table. A limit is strongly recommended for performance.

max_dimensional_values

integer | null

Maximum number of dimensional values to return per matched dimension.

limit

integer | null

Maximum number of distinct tables to return, paged in a stable order (by connection, catalog, schema, table). Only honored on the enumerate path (no query); ranked search is not pageable. Omit for the current unbounded behavior — every in-scope table is returned. When set, the total number of in-scope tables is reported on the Total-Count response header so the caller can compute the next offset, and top_n_results is ignored (the page window bounds the table count instead).

Required range: x >= 1

offset

integer | null

Number of tables to skip before the page (0-based), in the same stable order as limit. Only honored on the enumerate path. Omit or 0 for the first page.

Required range: x >= 0

Response

package_info

object | null

The package info for the result (can be null if the result is not scoped by a package)

Show child attributes

model_uri

string | null

The relative URI of the model for the result (can be null if the result is not scoped by a model)

source

string | null

The Malloy source for the result (can be null if the result is not scoped by a source)

source_docs

string | null

Documentation for the source (extracted from Malloy annotations)

score

number | null

Overall score for the result (for comparing multiple results)

matches

object[]

Show child attributes

Search semantic model context