Skip to main content
A custom domain route is the binding between a path on a verified custom domain and a concrete piece of content — a chatbot, a knowledge base, or a page. A custom domain on its own doesn’t route anything. Routes are how acme.com/, acme.com/support, and acme.com/docs end up serving different resources from the same hostname.

​
When to use a route

  • Hosting your chatbot at support.acme.com (one route, default slug).
  • Splitting one hostname into multiple destinations — acme.com/help for the knowledge base, acme.com/chat for the chatbot.
  • A microsite per product, each on its own subdomain.

​
Path model

Every route lives on exactly one custom domain and owns exactly one slug. The full URL is https://<domain>/<slug>. The combination (domain_id, slug) is unique — you can’t have two routes at the same path on the same domain. To re-point a path, delete the existing route and create a new one.
Slugs are lowercase alphanumeric + hyphen only (^[a-z0-9-]*$). A small list of slugs is reserved for platform internals (api, health, _next, .well-known, etc.) and cannot be used.

​
Resource types

Exactly one of chatbot_id, kb_id, or page_id is set on every route, and it must match the type discriminator: The referenced resource must belong to the same organization as the domain — the API rejects cross-org references with 400 invalid_payload.

​
Create a route

cURL
Response
The parent domain doesn’t need to be verified yet — routes can be configured up front and start serving the moment verification flips to true. POST /custom-domain-routes accepts an Idempotency-Key header so retries are safe. See Idempotency.
A domain can have at most one default route. If you create or PATCH a route with is_default: true while another route on the same domain is already the default, the request is rejected with 409. Clear is_default on the existing default route first (or move it with a single update), then set the new one.

​
List routes on a domain

domain_id is required — listing across every domain in an org isn’t supported.
cURL
Returns every route on the domain in a single envelope — the list is bounded by (domain_id, slug) uniqueness, so pagination isn’t necessary.

​
Update

PATCH /custom-domain-routes/{id} accepts slug and is_default. The route type and underlying resource id are immutable — delete and recreate to re-point a path.
cURL

​
Delete

cURL
Returns 204 No Content. The parent domain and the underlying chatbot/kb/page are untouched — only the binding is removed.
Deleting a route makes its URL fall through. If it was the default route (slug ""), the bare hostname returns the platform’s “domain configured but no routes” placeholder until you add a new default.

​
Permissions