NetBird Full API Reference + Read-Only MCP Prototype
POST/api/integrations/agent-network/managed-proxy

Provision a managed Agent Network gateway

Starts provisioning of a NetBird-managed Agent Network gateway for the account, allocating its endpoint under the managed zone on the first call. Idempotent — answers 202 when this call started (or, after a failure, restarted) provisioning and 200 when a deployment already exists, reporting current state either way. A disabled deployment answers 200 with state disabled and stays disabled. Returns 409 when the account already has an Agent Network endpoint that managed provisioning does not own, and 503 when endpoint allocation is temporarily exhausted.

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

7 status codes
200A managed gateway deployment already exists; reports its current state.
endpointstringrequired
The account's gateway hostname.
idstringrequired
Managed proxy deployment ID.
messagestringoptional
Failure detail reported by the rollout. Only set when state is `failed`.
regionstringoptional
Region of the cluster hosting the deployment.
statestringrequired
Derived deployment state. `provisioning` until the gateway is rolled out and connected, `ready` while the gateway actively serves the endpoint, `failed` when the rollout reported a failure, `disabled` while the gateway is turned off and the endpoint is not served.
Allowed:provisioningreadyfaileddisabled
202Provisioning started, or restarted after a reported failure
endpointstringrequired
The account's gateway hostname.
idstringrequired
Managed proxy deployment ID.
messagestringoptional
Failure detail reported by the rollout. Only set when state is `failed`.
regionstringoptional
Region of the cluster hosting the deployment.
statestringrequired
Derived deployment state. `provisioning` until the gateway is rolled out and connected, `ready` while the gateway actively serves the endpoint, `failed` when the rollout reported a failure, `disabled` while the gateway is turned off and the endpoint is not served.
Allowed:provisioningreadyfaileddisabled
401Requires authentication
403Forbidden
409The account already has an Agent Network endpoint not owned by managed provisioning
endpointstringrequired
The Agent Network endpoint already assigned to the account.
500Internal Server Error
503Endpoint allocation is temporarily exhausted; retry later
messagestringoptional
A human-readable error message.

Error handling

A 401 is returned: Requires authentication. A 403 is returned: Forbidden. A 409 is returned: The account already has an Agent Network endpoint not owned by managed provisioning. A 500 is returned: Internal Server Error. A 503 is returned: Endpoint allocation is temporarily exhausted; retry later.