> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure retrieval type and top_k for a Search collection.

Settings hold the collection's default retrieval configuration in their own subresource -- collection `PATCH` never touches them. Settings are accessed at `/v2/ai/collections/{uuid}/settings`, and any setting can be overridden per request at [search](/docs/ai-search/searching) time.

| Field            | Type    | Values                                        | Default  |
| ---------------- | ------- | --------------------------------------------- | -------- |
| `top_k`          | integer | 1--50                                         | 5        |
| `retrieval_type` | string  | `vector` (`hybrid` and `keyword` coming soon) | `vector` |

`retrieval_type` selects how a query is matched against the collection's indexed content -- see [Search Modes](/docs/ai-search/search-modes) for how the modes differ and when to use each.

<Warning>
  `hybrid` and `keyword` retrieval are coming soon. Keep `retrieval_type` set to `vector` -- a collection set to `hybrid` cannot be searched yet.
</Warning>

## Get Settings

```bash theme={null}
curl -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a/settings"
```

```json theme={null}
{
  "data": {
    "record_type": "ai_collection_settings",
    "retrieval": { "top_k": 5, "retrieval_type": "vector" }
  }
}
```

## Replace Settings

`PUT` replaces the entire settings object. Omitted keys reset to their defaults.

```bash theme={null}
curl -X PUT https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a/settings \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "retrieval": { "top_k": 25, "retrieval_type": "vector" } }'
```

## Merge Settings

`PATCH` does a partial merge at the `retrieval` key. Unnamed fields are preserved.

```bash theme={null}
curl -X PATCH https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a/settings \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "retrieval": { "top_k": 5 } }'
```

Returns the full merged settings object -- `retrieval_type` is unchanged.

## Validation Errors

Unsupported `retrieval_type` values return `422`:

```json theme={null}
{
  "errors": [{
    "code": "unsupported_retrieval_type",
    "title": "Unsupported retrieval type",
    "detail": "retrieval_type 'semantic' is not supported. Supported types: 'hybrid', 'vector'.",
    "source": { "pointer": "/retrieval/retrieval_type" }
  }]
}
```

`top_k` outside 1--50 returns `422` with code `invalid_top_k`. Unrecognized fields in the `retrieval` object are rejected with `400`.

## Related

* [Search Modes](/docs/ai-search/search-modes) -- vector, keyword, and hybrid compared
* [Collections](/docs/ai-search/manage-collections) -- create, list, retrieve, update, and delete collections
* [Sources](/docs/ai-search/sources) -- add, replace, and remove data sources