Administration

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

KindJobTypical model
llmChat, tools, conversations, and agentsA chat or reasoning model
embeddingDataset chunks and semantic memorybge-m3 or an equivalent 1,024-dimension deployment
guardrailSafety classificationA compatible safety classifier
routerOptional refinement for model: "auto"A small classification model
rerankerCross-encoder reranking after hybrid retrievalbge-reranker-v2-m3 or Cohere
searchWeb search for runs and plugin chatsnone: 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 typeRequired non-secret configCredential
openai, anthropic, gemini, groq, xai, mistral, cohere, openrouter, perplexitynoneapi_key
compatiblebase_urloptional api_key
ollamabase_urlnone
azureendpointapi_key
bedrockregionaccess_key, secret_key
vertexproject_id, regionauth_credentials
brave (kind search only)optional base_urlapi_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:

  • key is an immutable operator identifier;
  • models is the allowlist of upstream model IDs served by this connector;
  • an empty models list is a catch-all;
  • default_model is required and must appear in models when the list is non-empty;
  • requested model IDs are sent upstream verbatim;
  • higher priority is preferred, while weight distributes 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 models or default_model is 400.
  • An organization cannot register a search connector through /v1/org/connectors, which accepts llm only. 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 4xx such as an invalid key) is 400 and nothing is stored. No answer, 408, 429 or 5xx stores the connector and reports verification.status: "unreachable". skip_validation skips the check. The response shows the key only by its last characters (credential_hint).
  • POST /v1/connectors/{id}/verify runs the same check again; POST /v1/connectors/{id}/default makes one the default; POST /v1/connectors/{id}/disable and POST /v1/connectors/{id}/enable turn 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 }
}
  • name is optional and defaults to the provider's name.
  • Adding runs the same key check as a platform search connector. A definitive refusal is 400 with error.code: "search_key_refused" and nothing is stored; an outage stores the connector and reports verification.status: "unreachable". An unsupported type or an unknown secret is 400.
  • 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 …/default makes another the default and turns it on; …/disable and …/enable turn one off and on again (enabling never makes it the default); DELETE removes 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}/disable

Verification 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-models

An 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:

  1. an enabled connector that can serve its exact ID;
  2. a runtime pricing row;
  3. an organization model grant.

This separation lets operators rotate infrastructure, change commercial pricing, and change tenant entitlements independently.

On this page