NetBird Full API Reference + Read-Only MCP Prototype
POST/api/agent-network/providers

Create an Agent Network Provider

Connects a new Agent Network AI provider for the account.

The credential is checked against the vendor's model listing before the provider is stored, so a record the vendor will not accept is refused rather than saved. A rejected credential, a listing endpoint that does not resolve or answer, a vendor outage, and a timeout all block the write and return 422.

What that proves about the upstream URL is narrower than the URL itself. Only its host is used: the listing is requested over HTTPS at the path the catalog entry declares, so a configured scheme or path is neither used nor validated here. Where the catalog entry has a listing host of its own — Bedrock, whose listing comes from the control plane — even the host is only resolved, never contacted, so a public host that does not answer is still stored.

Only what cannot be checked at all is exempt and stored unverified: a catalog provider with no listing endpoint, one with no host to derive a listing from, an upstream resolving to a private address the management service will not dial, and a provider configured to skip TLS verification.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields

New provider request

api_keystringoptional
Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).
enabledbooleanoptional
Whether the provider is enabled. Defaults to true on create.
extra_valuesobjectoptional
Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). The request's map replaces the stored values; empty strings drop the corresponding key.
identity_header_groupsstringoptional
Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same semantics as `identity_header_user_id`.
identity_header_user_idstringoptional
Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. Empty or omitted disables stamping for this dimension.
metadata_disabledbooleanoptional
Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected).
modelsarray<object>optional
Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
namestringrequired
Display name for the provider.
provider_idstringrequired
Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
skip_tls_verificationbooleanoptional
Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false.
upstream_urlstringrequired
Full upstream URL (with scheme) that NetBird forwards traffic to.

7 status codes
200Provider created
created_atstringrequired
Timestamp when the provider was created.
enabledbooleanrequired
Whether the provider is enabled.
extra_valuesobjectoptional
Operator-typed values for catalog-declared extra headers. Keys are wire header names (e.g. `x-portkey-config`); values are the strings the proxy stamps on every upstream request to this provider. Catalog (AgentNetworkCatalogProvider.extra_headers) declares which keys are accepted; values not declared by the catalog are ignored at synth time. Empty / missing values mean no header stamped.
idstringrequired
Provider ID
identity_header_groupsstringrequired
Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
identity_header_user_idstringrequired
Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
metadata_disabledbooleanrequired
Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
modelsarray<object>required
Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
namestringrequired
Display name shown in the dashboard.
provider_idstringrequired
Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
skip_tls_verificationbooleanrequired
Whether upstream TLS certificate verification is skipped when the proxy dials this provider's URL. Intended for self-hosted / internal gateways behind a private or self-signed certificate.
updated_atstringrequired
Timestamp when the provider was last updated.
upstream_urlstringrequired
Full upstream URL (with scheme) that NetBird forwards traffic to.
400Bad Request
401Requires authentication
403Forbidden
409Conflict
messagestringoptional
A human-readable error message.
422Validation failed
500Internal Server Error

Error handling

A 400 is returned: Bad Request. A 401 is returned: Requires authentication. A 403 is returned: Forbidden. A 409 is returned: Conflict. A 422 is returned: Validation failed. A 500 is returned: Internal Server Error.