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

# Domain routing API

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/akua-1dce587a/AEEz0U2s7Do2sYaM/images/heros/api-domain-routing-light.svg?fit=max&auto=format&n=AEEz0U2s7Do2sYaM&q=85&s=a0aaf51fa6768e1b49d65a53a0312b2e" alt="An inbound hostname is resolved against three managed routing resources — workspace subdomain, preview hostname, and custom domain — then dispatched through the managed edge to the app via through_dispatcher or bypass_dispatcher" width="1536" height="864" data-path="images/heros/api-domain-routing-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/akua-1dce587a/AEEz0U2s7Do2sYaM/images/heros/api-domain-routing-dark.svg?fit=max&auto=format&n=AEEz0U2s7Do2sYaM&q=85&s=20e82be06c4a80f07376b31fc9924ff9" alt="An inbound hostname is resolved against three managed routing resources — workspace subdomain, preview hostname, and custom domain — then dispatched through the managed edge to the app via through_dispatcher or bypass_dispatcher" width="1536" height="864" data-path="images/heros/api-domain-routing-dark.svg" />
</Frame>

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.

<CardGroup cols={2}>
  <Card title="Workspace subdomains API" icon="at" href="/api-reference/workspace-subdomains/get-workspace-subdomain">
    Get and rename the workspace subdomain.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={2}>
  <Card title="Preview hostnames API" icon="link" href="/api-reference/preview-hostnames/list-preview-hostnames">
    List, bind, and delete preview hostnames for an installation.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={2}>
  <Card title="Custom domains API" icon="globe" href="/api-reference/custom-domains/list-custom-domains">
    Create, verify, update, and delete custom domains.
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="API introduction" icon="book-open" href="/apis/introduction">
    Authentication, pagination, idempotency, and error handling.
  </Card>

  <Card title="Preview domains" icon="globe" href="/networking/preview-domains">
    How managed preview hostnames route to your applications.
  </Card>

  <Card title="Authentication" icon="key" href="/apis/authentication">
    Set up API tokens for programmatic access.
  </Card>

  <Card title="Operations API" icon="clock" href="/api-reference/operations/list-operations">
    Track long-running infrastructure changes.
  </Card>
</CardGroup>