Settings

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. top_k can be overridden per request at search time; retrieval_type cannot — a per-request value is accepted but ignored, and meta.retrieval_type echoes the mode that actually ran.

Field	Type	Values	Default
`top_k`	integer	1—50	5
`retrieval_type`	string	`vector`, `hybrid` (`keyword` coming soon)	`vector`

retrieval_type selects how a query is matched against the collection’s indexed content — see Search Modes for how the modes differ and when to use each.

Keep retrieval_type set to vector. The other two modes are not ready, and they fail differently:

hybrid is accepted by this endpoint but a collection set to it cannot be searched yet.
keyword is rejected here with 422 unsupported_retrieval_type — it cannot be set at all.

Get Settings

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

{
  "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.

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.

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:

{
  "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.

Search Modes — vector, keyword, and hybrid compared
Collections — create, list, retrieve, update, and delete collections
Sources — add, replace, and remove data sources

AI Search

Concepts

Configuration

API

For AI Agents

Get Settings

Replace Settings

Merge Settings

Validation Errors

​Get Settings

​Replace Settings

​Merge Settings

​Validation Errors

​Related

Get Settings

Replace Settings

Merge Settings

Validation Errors

Related