Skip to main content
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 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.