---
title: "🛡️ Claim a vanity hostname for this server."
method: PUT
path: "/api/v1/connect/vanity"
tags: ["Remote Access"]
---

# 🛡️ Claim a vanity hostname for this server.

`PUT /api/v1/connect/vanity`

Answers from the Remote Access Server are passed through untouched, including its refusals: <code>422 invalid_name</code>, <code>409 name_unavailable</code> / <code>label_limit_reached</code>, <code>429 rename_cooldown</code>, <code>402 cert_unavailable</code> and <code>503 vanity_disabled</code>.<br /><hr /><h3>🛡️ Requires Capabilities: <code>ServerSettings.Update</code></h3>

## Request body

- SetVanityNameDto
  - `name` string, required — The vanity label to claim for this server, without any domain suffix.

## Response `200`

- VanityStatusResponse
  - `labels` string[], required — Every vanity label this server currently holds.
  - `primary` string, nullable, required — The label clients are pointed at, when one is set.
  - `state` 'pending' | 'live' | 'failed', nullable, required — Where the certificate covering the labels stands. `pending` means the name is claimed but not yet on a certificate.

## Other responses

- `400` — Possible reasons: Request validation failed, see response for details; Remote Access is not enabled on this server, or it holds no cloud credential.
- `401` — Possible reasons: The authorization token is invalid.
- `403` — Possible reasons: The user does not have sufficent capabilities.

## Changes

- **2026-08-22** `4d3a316ae17b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api/changes/api/v1/connect/vanity/put.md)

---

[API](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api.md) · [All operations](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardinalapps/cardinal-media-server-api/revisions/7b5e4555e84f/schema)