---
title: "Set an app's default link domain"
method: PUT
path: "/apps/{id}/link-domain"
tags: ["Apps"]
---

# Set an app's default link domain

`PUT /apps/{id}/link-domain`

## Request

- Base URL: `https://api.warplink.app/v1`
- URL: `https://api.warplink.app/v1/apps/{id}/link-domain`
- Auth: HTTP bearer

Chooses the default domain for the app's new links: aplnk.to (legacy apps only), the app's own subdomain, or a live custom domain. Reversible. Existing links keep their addresses, and no redirect is created. Needs an API key that has a creator. Send the link_handle and default_link_domain you last read, so a change made meanwhile is never overwritten. A request already at the requested default returns the current app without a change.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `domain` string, required: The hostname new links use by default. One of allowed_link_domains on the app.
  - `expected_link_handle` string, required: The app's link_handle as you last read it.
  - `expected_default_link_domain` string, required: The app's default_link_domain as you last read it.
  - `confirm` boolean: Must be true for a change. Without it a change is refused with 400 VALIDATION_ERROR.

## Response `200`

The app with its new default

- App
  - `id` string, uuid
  - `org_id` string, uuid
  - `name` string
  - `ios_bundle_id` string, nullable
  - `ios_team_id` string, nullable
  - `ios_app_store_id` string, nullable
  - `ios_app_store_url` string, uri, nullable
  - `ios_universal_link_paths` string[], nullable
  - `android_package_name` string, nullable
  - `android_sha256_fingerprints` string[], nullable
  - `android_play_store_url` string, uri, nullable
  - `android_app_links_paths` string[], nullable
  - `icon_url` string, uri, nullable
  - `icon_source` 'auto' | 'manual'
  - `probabilistic_matching` boolean: False means routing-only mode: the server no longer matches installs by probabilistic match or raw device signals for this app. Deep links keep working, and deferred links and attribution use only deterministic signals (the Android Play Install Referrer click id, and a device that already has an install). Defaults to true.
  - `link_handle` string: The lowercase subdomain label for this app's links, for example acme in acme.aplnk.to. Every app has one.
  - `link_domain` string: The full host derived from link_handle, for example acme.aplnk.to.
  - `legacy_apex_enabled` boolean: True for an app that existed when app subdomains launched. Its links on aplnk.to keep working and aplnk.to keeps listing the app for good.
  - `default_link_domain` string: The domain a new link gets when a create request names none: the saved default, or link_domain when none is saved. Change it with PUT /v1/apps/{id}/link-domain. It never changes a link that already exists.
  - `default_link_domain_available` boolean: False when the saved default is a custom domain that is no longer live. A link created with no domain then gets 409 DEFAULT_DOMAIN_UNAVAILABLE until you choose a domain or a new default.
  - `allowed_link_domains` string[]: The hostnames a new link for this app may use: the default first when it is available, then aplnk.to (legacy apps only), link_domain and the org's live custom domains.
  - `previous_link_handle` string, nullable: The app's old subdomain label while a rename period is open. null otherwise.
  - `previous_link_domain` string, nullable: The full old host while a rename period is open, for example oldname.aplnk.to. It keeps opening the app.
  - `rename_period_ends_at` string, date-time, nullable: The date shown for the open rename period. It is not a deadline and not a promise to move links that day. If links on the old subdomain later move to the new one, their old URLs redirect. null when no period is open.
  - `rename_period_extensions` integer: How many times the open rename period was extended by 1 month. At most 2.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: VALIDATION_ERROR for an invalid app ID or body, a domain the app cannot use (fields.domain), or a change without confirm (fields.confirm).
- `401`: Unauthorized
- `403`: Forbidden. ATTRIBUTED_KEY_REQUIRED for a key with no creator.
- `404`: Not found
- `409`: APP_LINK_STATE_CHANGED when the link_handle or default_link_domain you sent is no longer current. Read the app and review the settings before you retry.

---

[API](https://skmtc.dev/warplink/apis/warplink-api.md) · [All operations](https://skmtc.dev/warplink/apis/warplink-api/llms.txt) · [OpenAPI document](https://skmtc.dev/warplink/apis/warplink-api/revisions/2a90ae8c44e8?raw)