Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Retrievers

Get Retriever

Get a retriever by ID or name.

get/v1/retrievers/{retriever_id}

Path parameters

retriever_idstring required

Retriever ID or name.

Retriever ID or name.

Response

Successful Response

retriever_idstring

Stable retriever identifier (REQUIRED).

retriever_namestring required

Unique retriever name within namespace (REQUIRED).

descriptionstring nullable

Detailed description of retriever behaviour (OPTIONAL).

collection_idsstring[]

Collections queried by the retriever. Can be empty for query-only inference mode.

input_schemaobject

JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference.

tagsstring[]

Arbitrary tags to help organise retrievers (OPTIONAL).

metadataobject

Custom key-value metadata (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions.

display_configobject nullable

Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever.

versioninteger

Version number that increments on each update (REQUIRED).

created_atstring date-time

Creation timestamp in UTC (REQUIRED).

updated_atstring date-time

Last update timestamp in UTC (REQUIRED).

created_bystring nullable

Identifier of the user who created the retriever (OPTIONAL).

updated_bystring nullable

Identifier of the user who last updated the retriever (OPTIONAL).

is_publishedboolean

Whether this retriever is currently published (either as public retriever or in marketplace)

marketplace_listing_idstring nullable

Marketplace listing ID if this retriever is published to the marketplace, None otherwise

fusionstring nullable required

Fusion strategy used by this retriever's feature_search stage (e.g. 'learned', 'rrf', 'dbsf'). Null if no feature_search stage.

collection_identifiersstring[] required

Mirror of collection_ids under the field name CREATE accepts (collection_identifiers), so a create → read round-trip reads back the field it wrote. Always equal to collection_ids (FRUSTRATIONS 2026-07-16: SDKs/agents re-reading their own write saw collection_identifiers null and concluded the retriever was unscoped).

Example response

{
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "collection_ids": [
    "col_marketing_ads"
  ],
  "input_schema": {
    "query_text": {
      "description": "Full-text query",
      "type": "string"
    }
  },
  "retriever_id": "ret_abc123",
  "retriever_name": "executive_ads_search",
  "stages": [
    {
      "config": {
        "parameters": {
          "field": "metadata.spend",
          "operator": "gt",
          "value": 1000
        },
        "stage_name": "attribute_filter",
        "version": "v1"
      },
      "name": "filter_high_spend",
      "stage_type": "filter"
    }
  ]
}