Skip to content

Update the cluster's private link

PUT
/clusters/{cluster_id}/private-link
curl --request PUT \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/private-link \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": true, "azure_subscription_ids": [ "example" ] }'

Turns Azure private link on or off and sets the Azure subscription IDs. The alias is returned once private link is enabled. Connections are approved afterwards, per listed subscription, so status moves from waiting to connected once a private endpoint from a listed subscription connects.

Returns 403 when the workspace’s plan lacks the private_network feature, and 422 when the cluster’s site has no Azure private link or the subscription IDs are not valid.

Required scope: clusters:private-link:write

cluster_id
required
string format: uuid
API-Version
required
string
Allowed values: 2026-06-01.beta
Media typeapplication/json

Turns a cluster’s Azure private link on or off and sets its subscription IDs.

object
enabled
required

Turn private link on or off.

boolean
azure_subscription_ids

Azure subscription IDs (GUIDs, at most 20) allowed to connect. Replaces the stored list; an empty list clears it. When omitted the stored list is kept. At least one is required to enable.

Array<string>

Example generated

{
  "enabled": true,
  "azure_subscription_ids": [
    "example"
  ]
}

The request has succeeded.

Media typeapplication/json

A cluster’s Azure private link.

object
enabled
required

Whether private link is on.

boolean
azure_subscription_ids
required

Azure subscription IDs allowed to connect a private endpoint, lowercase GUIDs.

Array<string>
alias

Private Link Service alias to paste when creating the private endpoint in Azure. Only present while private link is enabled.

string
dns_name

Private hostname to create in your private DNS zone. Only present while private link is enabled.

string
status
required

Status of a cluster’s private link.

string
Allowed values: disabled waiting connected
connections

Connection state of each subscription seen so far. A subscription with no private endpoint yet is absent.

Array<object>

The private endpoint connection of one Azure subscription.

object
subscription_id
required

Azure subscription ID, a GUID.

string
status
required

Connection state of one subscription’s private endpoint.

string
Allowed values: waiting connected rejected

Example

{
  "status": "disabled",
  "connections": [
    {
      "status": "waiting"
    }
  ]
}

Access is unauthorized.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Access is forbidden.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

The server cannot find the requested resource.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Client error

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri
errors
required
Array<object>
>= 1 items
object
field
required
string
detail
required
string
code
string
value

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

Client error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}
Retry-After
integer
RateLimit-Limit
integer
RateLimit-Remaining
integer
RateLimit-Reset
integer
X-RateLimit-Limit-Second
integer
X-RateLimit-Remaining-Second
integer
X-RateLimit-Limit-Minute
integer
X-RateLimit-Remaining-Minute
integer
X-RateLimit-Limit-Hour
integer
X-RateLimit-Remaining-Hour
integer
X-RateLimit-Limit-Day
integer
X-RateLimit-Remaining-Day
integer

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}