Connectors

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

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`

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.

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.

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

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.

On this page