---
title: "Update domain settings"
method: PATCH
path: "/api/domains/{id}"
tags: ["Domains"]
---

# Update domain settings

`PATCH /api/domains/{id}`

## Request

- Base URL: `https://www.flyn.to`
- URL: `https://www.flyn.to/api/domains/{id}`
- Auth: HTTP bearer

Updates `placeholder` and/or `notFoundUrl` on a domain in the caller's scope. Both values are stored, but nothing at runtime reads them yet.

**Auth:** API key (`Bearer flyn_sk_live_...`), or the signed-in dashboard session cookie when no API key header is sent. MCP OAuth access tokens are not accepted here and get 401.

**Plan:** every plan.

**Rate limit:** 10 requests per 60 s per client IP, fixed window, in memory per server instance, checked before authentication.

A missing, foreign or malformed id returns 500 "Operation failed", not 404.

## Request body

- DomainUpdateRequest
  - `placeholder` string, nullable: Stored as sent (at most 500 characters). Not read at runtime yet.
  - `notFoundUrl` string, nullable: null or "" clears it. Otherwise an http or https URL that does not resolve to a private address. Not read at runtime yet.

## Response `200`

Updated (an empty body only bumps updated_at).

- DomainEnvelope
  - `domain` Domain, required: A custom domain row, returned with its database column names.
    - `id` string, uuid, required
    - `user_id` string, uuid, required: Who added it.
    - `team_id` string, uuid, nullable, required: Workspace it belongs to, or null for a personal domain.
    - `domain` string, required: Lower-case host, for example go.brand.com.
    - `slug` string, required: The domain with dots replaced by hyphens. Unique, so a-b.com and a.b.com collide.
    - `verified` boolean, required
    - `status` 'pending' | 'active' | 'invalid' | 'expired', required
    - `txt_record` string, nullable, required: Ownership token to publish as a TXT record, `flyn-verify=<32 hex>`.
    - `cname_target` string, nullable, required: Routing target: an A record value for an apex domain, otherwise a CNAME target.
    - `last_checked_at` string, date-time, nullable
    - `verified_at` string, date-time, nullable
    - `placeholder` string, nullable: Stored placeholder text. Nothing at runtime reads it yet.
    - `not_found_url` string, nullable: Stored not-found URL. Nothing at runtime reads it yet: an unknown slug always gets the standard dead-link response.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `pause_warned_at` string, date-time, nullable
    - `pause_scheduled_at` string, date-time, nullable
    - `paused_at` string, date-time, nullable: Set when the domain is paused; links on a paused domain stop redirecting.

## Other responses

- `400`: Messages: "Placeholder must be a string", "Placeholder must be under 500 characters", "Only HTTP/HTTPS URLs allowed", "Invalid not-found URL".
- `401`: No valid API key and no dashboard session. Messages: "Invalid or revoked API key", "API key has expired", "Unauthorized. Sign in to the dashboard, or pass a Bearer API key in the Authorization header.", or "Unauthorized" when the session lookup itself fails. An MCP OAuth token lands here too.
- `403`: The account is suspended.
- `429`: More than 10 requests in the window. Counted per client IP. Retry-After gives the seconds until the window resets.
- `500`: Invalid JSON, domain not found or not in scope, or a database error.

---

[API](https://skmtc.dev/flyn/apis/flyn-api.md) · [All operations](https://skmtc.dev/flyn/apis/flyn-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flyn/apis/flyn-api/revisions/977962a98ccb?raw)