Connectors
Configure model providers, embeddings, routing, guardrails, and reranking.
A connector is an encrypted upstream provider configuration. Platform connectors serve all eligible organizations; an organization may also register its own LLM connector when bring-your-own-key is enabled by the provider model.
Connections are different: a connection belongs to an end user and exposes personal tools such as Gmail or Outlook.
Connector kinds
| Kind | Job | Typical model |
|---|---|---|
llm | Chat, tools, conversations, and agents | A chat or reasoning model |
embedding | Dataset chunks and semantic memory | bge-m3 or an equivalent 1,024-dimension deployment |
guardrail | Safety classification | A compatible safety classifier |
router | Optional refinement for model: "auto" | A small classification model |
reranker | Cross-encoder reranking after hybrid retrieval | bge-reranker-v2-m3 or Cohere |
search | Web search for runs and plugin chats | none: a search connector serves no models |
No guardrail connector means classifier-based screening is not provisioned. If a configured guardrail or reranker becomes unavailable, affected calls fail closed rather than silently bypassing that control.
Supported providers
| Provider type | Required non-secret config | Credential |
|---|---|---|
openai, anthropic, gemini, groq, xai, mistral, cohere, openrouter, perplexity | none | api_key |
compatible | base_url | optional api_key |
ollama | base_url | none |
azure | endpoint | api_key |
bedrock | region | access_key, secret_key |
vertex | project_id, region | auth_credentials |
brave (kind search only) | optional base_url | api_key |
Provider capabilities differ. For example, Anthropic serves chat but not embeddings; Cohere can serve chat, embeddings, and reranking; compatible and Ollama endpoints can serve only the capabilities exposed by that deployment.
Register a connector
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/connectors" -d '{
"key":"anthropic-production",
"name":"Anthropic production",
"kind":"llm",
"type":"anthropic",
"api_key":"sk-ant-...",
"models":["claude-sonnet-4-5","claude-opus-4-1"],
"default_model":"claude-sonnet-4-5",
"priority":100,
"weight":1,
"default":true
}'Important fields:
keyis an immutable operator identifier;modelsis the allowlist of upstream model IDs served by this connector;- an empty
modelslist is a catch-all; default_modelis required and must appear inmodelswhen the list is non-empty;- requested model IDs are sent upstream verbatim;
- higher
priorityis preferred, whileweightdistributes traffic between equivalent candidates.
Register a search connector
A search connector gives the platform web search. Brave is the provider; its
key comes from a Brave Search API plan that includes the LLM context endpoint.
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/connectors" -d '{
"key":"brave-search",
"name":"Brave Search",
"kind":"search",
"type":"brave",
"api_key":"BSA...",
"priority":100,
"default":true
}'- A search connector serves no models: sending
modelsordefault_modelis400. - An organization cannot register a search connector through
/v1/org/connectors, which acceptsllmonly. An application can bring its own; see An application's own search connectors. - Registration runs one tiny real search with the key before storing it. A
definitive refusal from Brave (a
4xxsuch as an invalid key) is400and nothing is stored. No answer,408,429or5xxstores the connector and reportsverification.status: "unreachable".skip_validationskips the check. The response shows the key only by its last characters (credential_hint). POST /v1/connectors/{id}/verifyruns the same check again;POST /v1/connectors/{id}/defaultmakes one the default;POST /v1/connectors/{id}/disableandPOST /v1/connectors/{id}/enableturn one off and on again (enabling never makes it the default).- Every search reads the enabled search connectors afresh: the default first,
then by
priority, falling back to the next when one is unavailable. A change applies to the very next search, with no restart. - With no enabled search connector, a search fails with the reason
no_search_connector, never with an empty result, and plugin chats are not offered web search.
An application's own search connectors
An application can bring its own web search key for the organizations it owns.
It manages its search connectors with its application credential
(application-admin) on the application lane. The credential names the
application, so no path or body carries an application id, and another
application's connector is 404 on every route.
GET /v1/application/search-connectors
GET /v1/application/search-connectors/providers
POST /v1/application/search-connectors
POST /v1/application/search-connectors/{id}/default
POST /v1/application/search-connectors/{id}/disable
POST /v1/application/search-connectors/{id}/enable
DELETE /v1/application/search-connectors/{id}GET …/providers lists the providers a search connector can use, with the
secrets each needs. Today that is Brave only:
{"providers":[{"type":"brave","name":"Brave Search","secret_fields":["api_key"],"config_fields":[]}]}Add one:
curl -H "Authorization: Bearer $APPLICATION_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/application/search-connectors" -d '{
"type":"brave",
"name":"Our Brave",
"secrets":{"api_key":"BSA..."}
}'{
"id": "6f1c…",
"name": "Our Brave",
"type": "brave",
"enabled": true,
"default": true,
"credential_hint": "…9z9z",
"created_at": "2026-11-14T09:30:00Z",
"verification": { "status": "passed", "latency_ms": 312 }
}nameis optional and defaults to the provider's name.- Adding runs the same key check as a platform search connector. A definitive
refusal is
400witherror.code: "search_key_refused"and nothing is stored; an outage stores the connector and reportsverification.status: "unreachable". An unsupportedtypeor an unknown secret is400. - The key is only ever shown by its last characters (
credential_hint); no response returns it. - The application's first connector becomes its default.
POST …/defaultmakes another the default and turns it on;…/disableand…/enableturn one off and on again (enabling never makes it the default);DELETEremoves it and its key (204). - Every change is audited (
application_search_connector.*) and applies to the very next search, with no restart.
The list says which connector the application's organizations' next search
uses, in effective:
{
"connectors": [
{ "id": "6f1c…", "name": "Our Brave", "type": "brave", "enabled": true,
"default": true, "credential_hint": "…9z9z", "created_at": "2026-11-14T09:30:00Z" }
],
"effective": { "source": "application", "type": "brave", "name": "Our Brave" }
}effective.source is application when the application's own connector
serves the search, platform when the platform's does, and every field of
effective is null when no search connector is enabled anywhere.
Which connector serves a search. A search by one of the application's organizations uses the application's enabled search connectors, the default first, then oldest first. Only when the application has none enabled does it use the platform's, the platform default first. The two never mix in one search: when the application's own connectors all fail, the search fails; it does not fall back to the platform's. Search memory belongs to the connector, so switching connectors starts with none.
Discover models before registration
Discovery is best-effort and does not persist anything:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/connectors/discover-models" -d '{
"type":"openai",
"kind":"llm",
"api_key":"sk-..."
}'A structurally valid request returns 200 with models and a typed outcome:
provider, unsupported, rejected, or unreachable. Discovery never adds
pricing or organization grants. Cohere discovery uses the connector kind to
filter its catalog (reranker requests endpoint=rerank). In the console,
you can always enter an exact model ID manually when discovery is unavailable
or when a newly released model is not listed yet.
Verify and manage
GET /v1/connectors
POST /v1/connectors/{id}/verify
POST /v1/connectors/{id}/default
POST /v1/connectors/{id}/disableVerification performs a stateless real provider probe appropriate to the kind:
one-token chat, a tiny embedding, or a fixed query/document rerank. Compatible
rerankers use {base_url}/v1/rerank; Cohere rerankers use its
Bearer-authenticated /v2/rerank. Disabling a connector removes it from
routing without deleting its audit and billing provenance.
Edit metadata or rotate a key
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-H "Content-Type: application/json" \
-X PATCH "$BASE_URL/v1/connectors/$CONNECTOR_ID" -d '{
"name":"Anthropic production — rotated",
"api_key":"sk-ant-new-..."
}'name, models, default_model, priority, and weight are mutable.
Supplying api_key or secrets rotates the entire credential bag after a
verification probe. key, type, kind, and ownership scope are immutable;
create a new connector to change them.
Organization BYO key
Organization administrators can manage LLM-only connectors through:
POST /v1/org/connectors
GET /v1/org/connectors
PATCH /v1/org/connectors/{id}
POST /v1/org/connectors/{id}/default
POST /v1/org/connectors/{id}/disable
POST /v1/org/connectors/discover-modelsAn organization's connector is tried before platform connectors for the same model. Model grants still apply, and provider/model combinations with endpoint-local names may be ineligible for BYO-key routing.
Separation of concerns
Registering a connector does not publish a model. A usable model requires:
- an enabled connector that can serve its exact ID;
- a runtime pricing row;
- an organization model grant.
This separation lets operators rotate infrastructure, change commercial pricing, and change tenant entitlements independently.