Domain routing API

Manage workspace subdomains, preview hostnames, and custom domains through the public API

The domain routing API lets you manage the public hostnames that route traffic to your applications. Use it when you want automation to create preview URLs, attach customer-owned domains, or rename the workspace subdomain that appears in generated hostnames.

Domain routing is independent of how an application was installed. Installations can publish one or more preview hostnames, workspaces own their default subdomain, and custom domains belong to the workspace that controls the DNS relationship.

Resource model

Resource	Scope	Use it for
Workspace subdomain	Workspace	The default workspace slug used in managed preview hostnames.
Preview hostname	Installation	A managed hostname for one application endpoint.
Custom domain	Workspace	A domain you own and attach to a workspace for production traffic.

Workspace-scoped requests resolve the workspace from your credential the same way as the rest of the API — implied by a workspace API token, or selected with the optional Akua-Context header for broad credentials. Mutation endpoints are safe to retry with Idempotency-Key.

Workspace subdomains

Every workspace has one subdomain resource. Read it before showing a rename form, and pass the returned etag when you submit a rename. If another client changed the subdomain first, the API returns a conflict so your UI can reload the current value.

Workspace subdomains API

Get and rename the workspace subdomain.

Preview hostnames

Preview hostnames expose one installation endpoint through an Akua-managed hostname. Use pinned hostnames when you need a stable name for a known environment. Use floating hostnames when automation needs a fresh preview name without coordinating a specific slug.

Preview hostnames API

List, bind, and delete preview hostnames for an installation.

Custom domains

Custom domains attach a domain you control to a workspace. The API returns the DNS verification state so you can guide customers through domain control validation before serving production traffic.

Routing mode controls where traffic goes after the domain is active:

• through_dispatcher routes through Akua-managed edge dispatching.
• bypass_dispatcher is for enterprise traffic paths that use a dedicated target instead of the shared dispatcher.

Custom domains API

Create, verify, update, and delete custom domains.

Long-running changes

Domain mutations return an operation. Store the operation ID and call the operation :wait endpoint when you need synchronous handoff behavior.

For dashboards and CLIs, prefer showing the operation timeline instead of repeatedly fetching the domain resource. The operation response tells you when the routing change has been accepted and when background validation finishes.

Related topics

API introduction

Authentication, pagination, idempotency, and error handling.

Preview domains

How managed preview hostnames route to your applications.

Authentication

Set up API tokens for programmatic access.

Operations API

Track long-running infrastructure changes.