---
title: "Replace the hostname lists"
method: PUT
path: "/sites/{id}/settings/hostnames"
tags: ["Sites"]
---

# Replace the hostname lists

`PUT /sites/{id}/settings/hostnames`

## Request

- Base URL: `https://statable.com/api/v1`
- URL: `https://statable.com/api/v1/sites/{id}/settings/hostnames`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/statable/apis/statable-stats-api/docs/sites/:id/settings/hostnames/put.ts> (a function with typed inputs; its response is checked against the schema)

Owner or admin only; replaces the whole list. Unlike the dashboard equivalent this answers 400/500 on a bad body or a failed write instead of 200 with success:false — a status-checking client must not read a failure as done. Refused with `409 site_domain_blocked` when the lists would block the site's own domain while that domain is sending events (last 7 days): saved, such a list would silently drop all of the site's traffic. Nothing is written.

## Request body

- HostnameListRequest: Replaces both lists. Send [] to clear one. Each entry is reduced to its hostname — a pasted URL keeps only the host (`https://example.com/` is stored as `example.com`), an IDN is stored as punycode — and a listed host also covers its subdomains. An entry that is still not a hostname (a wildcard, a space, an empty label) fails the whole request with 400 `invalid_request` and nothing is changed.
  - `allowed` string[]
  - `blocked` string[]

## Response `200`

Applied.

- SettingsCount
  - `site_id` integer, required
  - `count` integer, required: Entries stored after the replace.

## Other responses

- `400`: `invalid_request` — the body or a field is not acceptable.
- `401`: Missing/malformed/invalid/revoked bearer token (`unauthorized`), or a key past its expiry (`key_expired`; the message names the expiry time).
- `403`: `insufficient_scope`, `key_not_scoped`, or `not_site_owner`.
- `404`: `write_disabled` or `unknown_site`.
- `409`: `site_domain_blocked` — the lists would block the site's own domain, which sent events in the last 7 days. The message names the domain and its share of the site's events.
- `429`: Hourly account (default 2000/h) or per-key (default 600/h) limit hit (`rate_limited`). Retry after the `Retry-After` seconds. The X-RateLimit-* headers report the window that tripped (account on an account limit).
- `500`: Unexpected server error (`internal`). Report it with the `request_id` from the body or the X-Request-ID header: it is what lets the exact log entry be found, and without it a 500 can only be matched by guessing at a time window.

---

[API](https://skmtc.dev/statable/apis/statable-stats-api.md) - [All operations](https://skmtc.dev/statable/apis/statable-stats-api/llms.txt) - [OpenAPI document](https://skmtc.dev/statable/apis/statable-stats-api/revisions/352b6d47c186?raw)