> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Custom URLs

> Create, list, update, delete and health-check an organization's custom-URL catalog — the reusable redirect destinations resolution rules point at — the programmatic equivalent of the dashboard's Custom URLs page.

Programmatic equivalent of the dashboard's `resolver/custom-urls/` page. The
custom-URL catalog holds an organization's reusable redirect destinations; a
resolution rule with the `CUSTOM_URL` destination points at one of them.

## When to use

* A brand owner wants to add, correct or retire a destination URL (a campaign
  page, a regional site) before or after pointing rules at it.
* A brand owner wants to know whether a destination is healthy.

A custom URL on its own redirects nothing. Scans only go there once a rule
points at it (see `manage-resolution-rules`).

## Auth

`X-API-Key` header or OAuth token with `resolver:write` scope (`resolver:read`
for reads). Reading needs view access to the organization; creating, updating,
deleting and re-checking need contribute access, and answer `404` without it.

## Flow

```
GET    /resolver/api/v1/organizations/{organization_id}/custom-urls
POST   /resolver/api/v1/organizations/{organization_id}/custom-urls
PUT    /resolver/api/v1/organizations/{organization_id}/custom-urls/{custom_url_id}
DELETE /resolver/api/v1/organizations/{organization_id}/custom-urls/{custom_url_id}
POST   /resolver/api/v1/organizations/{organization_id}/custom-urls/{custom_url_id}/retry
```

* **`GET` list** — every entry ordered by URL, paginated (`{data, pagination}`),
  each with `id`, `url`, `status` and `last_checked_at`.
* **`POST` create** — body `{"url": "https://..."}`: an absolute `http(s)` address
  of at most 2048 characters. `409` if the organization already has that
  address.
* **`PUT` update** — body `{"url": ...}`. The entry's health resets to
  `UNKNOWN` until it is checked again. `409` on an address collision.
* **`DELETE`** — `409` while a `CUSTOM_URL` resolution rule still points at the
  entry; re-point or remove those rules first.
* **`POST` retry** — runs a health check now and returns the refreshed entry.

## Health

`status` is `UNKNOWN` (never checked), `HEALTHY`, `DEGRADED` (intermittent
failures) or `UNREACHABLE`. It is set by the monitor and cannot be written. A
rule whose custom URL is unreachable follows its `on_custom_url_dead` policy:
skip the rule, or fall back to the Closient-hosted page.

## Verify

Re-read the list and `retry` each entry you added or changed until its status is
`HEALTHY`. To prove a destination is live for consumers, point a rule at it and
resolve a GTIN (MCP tool `resolve_gtin`, or `GET /01/<gtin>` without following
redirects) as described in `manage-resolution-rules`.