> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /retrieval-public-api.yaml post /get_context openapi: 3.0.0 info: title: Retrieval Public API description: Public API for retrieving semantic model contents. version: v1 servers: - url: https://{organization}.retrieval.credibledata.com/api/v1/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: retrieval description: Core retrieval API endpoints paths: /get_context: post: tags: - retrieval summary: Search semantic model context description: > 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. operationId: getContext requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetContextRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetContextResponse' '400': description: >- The request was malformed or cannot be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Insufficient permissions or the state of the system prevents the operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: >- An upstream service (e.g., LLM provider) returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '504': description: An upstream service (e.g., LLM provider) timed out. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: GetContextRequest: description: Request body for the get_context endpoint type: object required: - search_targets properties: search_targets: description: >- Typed search targets describing what to find. Each target specifies a target type and optional search text for semantic matching. type: array items: $ref: '#/components/schemas/SearchTarget' scopes: description: >- Optional list of scopes to narrow the search. Results will be scoped to the union of these. type: array items: $ref: '#/components/schemas/ResourceId' nullable: true filter_params: description: > 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. type: object additionalProperties: true nullable: true user_prompt: description: > 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. type: string nullable: true limit: description: | 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. type: integer minimum: 1 nullable: true offset: description: | 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. type: integer minimum: 0 nullable: true GetContextResponse: description: Response from the get_context endpoint type: object required: - sources properties: sources: description: >- Matched sources sorted by relevance then prominence (empty when no good matches) type: array items: $ref: '#/components/schemas/SourceResult' ranking: description: | 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). type: string enum: - relevance - prominence nullable: true total_available: description: | 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. type: integer nullable: true returned: description: | Number of sources included in this response. Always populated by current servers; optional only so clients tolerate responses from servers predating this field. type: integer nullable: true next_offset: description: | 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. type: integer nullable: true warnings: description: >- Optional warnings about the result set (e.g. when results were truncated or capped). Omitted when empty. type: array items: type: string nullable: true ErrorResponse: description: Standard error response type: object required: - error_code - message properties: error_code: type: string enum: - INVALID_INPUT - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - INTERNAL_ERROR - BAD_GATEWAY - GATEWAY_TIMEOUT message: type: string details: type: string nullable: true SearchTarget: description: >- Describes a single target type to search for, with optional text for semantic matching. type: object required: - target_type properties: target_type: $ref: '#/components/schemas/SearchTargetTypeEnum' description: The type of semantic model content to search for search_text: description: > String for semantic matching; null returns the most prominent items ranked by usage. - For `source`: brief description of the data domain (e.g., "ecommerce order data"). - For `dimension`: brief description of the attribute (e.g., "the geographic region of the customer"). - For `measure`: brief description of the metric (e.g., "the total revenue"). - For `view`: brief description of the desired analysis (e.g., "sales by region summary"). - For `dimensional_value`: the exact string value to match (e.g., "New York", "active"). type: string nullable: true ResourceId: description: >- Flat identifier for a resource within the semantic model hierarchy. The optional fields form a hierarchy — if a lower-level field is set, all fields above it must also be set (e.g., setting `source` requires `model_path`). type: object required: - environment - package properties: environment: description: The environment containing the package. type: string package: description: The package name. type: string version: description: The package version. When omitted, the pinned version is used. type: string nullable: true model_path: description: >- Relative path to the model file within the package (e.g., "model.malloy"). Required if `source` is set. type: string nullable: true source: description: The source name within the model. Required if `entity_name` is set. type: string nullable: true entity_name: description: >- The name of a specific entity to scope to (e.g., a dimension for dimensional value searches). type: string nullable: true SourceResult: description: >- A matched source with metadata and a list of entities from the source. Fields that would be null are omitted from the response. type: object required: - source_info properties: source_info: $ref: '#/components/schemas/SourceInfo' relevance: description: >- How relevant this source is to the search on a [0, 1] scale (higher is better). Derived from source-level matching when available, otherwise from entity relevance scores. Omitted when just listing sources. type: number prominence: description: >- How prominent this source is based on query usage patterns (higher is better). type: number matched_targets: description: >- Search targets that matched at the source level. Only includes targets with non-null search_text (listing operations are excluded). Omitted when empty (e.g., entity-level searches). type: array items: $ref: '#/components/schemas/MatchedTarget' entities: description: >- Deduplicated entities from the source, sorted by relevance then prominence. Omitted when empty. type: array items: $ref: '#/components/schemas/SourceEntity' SearchTargetTypeEnum: description: | The type of content a search target refers to: - `source` — data sources that wrap and extend tables. - `dimension` — categorical fields for grouping/filtering. - `measure` — aggregation metrics (counts, sums, averages). - `view` — pre-built analyses or named queries. - `dimensional_value` — exact categorical values within a dimension. type: string enum: - source - dimension - measure - view - dimensional_value SourceInfo: description: >- Identification and metadata for a matched source. Fields that would be null are omitted from the response. type: object required: - resource_id properties: resource_id: $ref: '#/components/schemas/ResourceId' docs: description: Documentation for the source (extracted from Malloy annotations) type: string summary: description: >- LLM-generated summary of the source. Only present when source-type search targets were used type: string filter_params: description: >- Filters defined in the source that can be supplied to subset the source contents. Omitted when empty. type: array items: $ref: '#/components/schemas/Filter' givens: description: >- Model-level `given:` runtime parameters in scope for this source. Each entry names a parameter the caller can supply on `execute_query` to override the model's default. Omitted when the source's model declares no givens. type: array items: $ref: '#/components/schemas/Given' authorize: description: > Access-gate expressions declared on this source via `#(authorize)` and file-level `##(authorize)` annotations. Publisher evaluates the full set as a single OR disjunction at query time and returns HTTP 403 when no expression grants access. Each entry lists the raw expression and the given names it references; if the caller's identity cannot satisfy any gate the query will be denied. Omitted when the source is unrestricted. type: array items: $ref: '#/components/schemas/Authorize' MatchedTarget: description: >- A search target (with non-null search_text) that matched at the source or entity level. Fields that would be null are omitted from the response. type: object required: - search_text - relevance properties: search_text: description: The search string that produced this match type: string relevance: description: Semantic match score on a [0, 1] scale (higher is better) type: number match_reason: description: Why this matched the search target (from LLM evaluation) type: string SourceEntity: description: >- A dimension, measure, or view belonging to a source in the semantic model. Fields that would be null are omitted from the response. type: object required: - name - entity_type properties: name: description: >- Exact Malloy field path (e.g., "hiring_manager.employee_count" for joined fields) type: string entity_type: $ref: '#/components/schemas/SourceEntityTypeEnum' description: The type of entity relevance: description: >- Best semantic match score across all matched targets on a [0, 1] scale (higher is better). Omitted when the entity was not matched semantically (e.g., usage-ranked listing or dimensional value match only). type: number prominence: description: >- How prominent this entity is based on query usage patterns (higher is better). Normalized score reflecting how frequently this entity appears in real queries. type: number data_type: description: The data type of the field type: string description: description: Description of what this entity represents type: string values: description: >- Matched dimensional values (dimensions only), sorted by relevance. Omitted when empty. type: array items: $ref: '#/components/schemas/DimensionalValue' values_indexed: description: >- When true, the dimension's values are individually indexed and can be searched with `dimensional_value` targets. Only present on dimensions. type: boolean code: description: >- The entity's Malloy code definition. Returned only when the request scopes to a specific entity (a scope with `entity_name`); omitted on broad searches. type: string matched_targets: description: >- Search targets that matched this entity and with what relevance. Only includes targets with non-null search_text. Omitted when the entity appears due to dimensional value matches or from a usage-ranked listing. type: array items: $ref: '#/components/schemas/MatchedTarget' Filter: description: > A filter declared on a source via a `#(filter)` annotation. Describes a single parameterized filter the source exposes at query time — the filter's human-readable `name`, comparator `type`, the underlying dimension it targets, and whether supplying a value is mandatory. type: object required: - name - type properties: name: description: >- The filter's `name=` label — the human-readable identifier for this filter, used as the key when supplying a filter value at query time. type: string type: description: > The comparator type applied to the underlying dimension. Determines the value shape expected when supplying a filter value at query time: - `equal`, `like`, `greater_than`, `less_than` → a single scalar string value - `in` → an array of string values type: string enum: - equal - in - like - greater_than - less_than dimension: description: >- The name of the underlying dimension the filter applies to. Informational only — filter values are keyed by `name`, not `dimension`. type: string required: description: >- When true, a value for this filter must be supplied when querying the source; otherwise the query will fail with a filter validation error. type: boolean Given: description: >- A `given:` runtime parameter declared on the source's model. The publisher reports this on every `SourceInfo` whose model has givens, so a caller iterating sources sees what runtime values it can supply without a second lookup. type: object required: - name - type properties: name: description: >- Name as declared in the model. Use this as the key when supplying a value on `execute_query`. type: string type: description: >- Rendered Malloy type (e.g. `string`, `number`, `boolean`, `date`, `timestamp`, `filter`). Determines the value shape expected at query time. type: string annotations: description: >- Annotations attached to the given declaration. May include `description=` etc. type: array items: type: string default: description: >- The given's declared default rendered as a Malloy source literal (`'WN'`, `2003`, `@2024-01-01`, `f'WN'`). Omitted when no default is declared. Hint for clients; omitting the given on `execute_query` uses the default. type: string Authorize: description: > An `#(authorize)` gate expression declared on a source, or a file-level `##(authorize)` expression in scope on the source's model. The publisher evaluates all in-scope expressions as a single OR disjunction at query time; access is granted when at least one expression returns `true`. Givens referenced in the expression must be supplied by a trusted middle tier — gates over caller-asserted givens are not a real boundary on their own. type: object required: - expression - given_names properties: expression: description: >- The raw Malloy boolean expression as authored (e.g. `$ROLE = 'analyst'`). Use only for display; do not attempt to evaluate it caller-side. type: string given_names: description: >- Names of the givens referenced by this expression, extracted from `$NAME` tokens. Lets a caller check whether its trusted context can satisfy the gate before executing a query. type: array items: type: string SourceEntityTypeEnum: description: The type of source entity type: string enum: - view - measure - dimension DimensionalValue: description: >- A dimensional value matched from search (always nested in its corresponding dimension). Fields that would be null are omitted from the response. type: object required: - value properties: value: description: The actual value found type: string relevance: description: >- Semantic match score on a [0, 1] scale (higher is better). Omitted when listed without semantic matching. type: number prominence: description: >- How prominent this value is based on query usage patterns (higher is better). type: number search_text: description: The search string that was used to find this value type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Auth0-issued user JWT. Provide as `Authorization: Bearer `. apiKeyAuth: type: apiKey in: header name: Authorization description: | HMAC-signed API key JWT issued by Credible. Provide as `Authorization: ApiKey ` (note the `ApiKey ` prefix in place of the usual `Bearer `). Include the full string — prefix and token — in this field. ````