---
title: "Add or reassign a subdomain"
method: POST
path: "/subdomains/v1"
tags: ["Subdomains"]
---

# Add or reassign a subdomain

`POST /subdomains/v1`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/subdomains/v1`
- Auth: HTTP bearer

Maps a managed subdomain ({name}.run402.com) to a site deployment. The target is resolved server-side from whatever the caller holds: `deployment_id` (a legacy `dpl_` id, or a `rel_` / `op_` id from a unified-apply commit), `release_id`, or neither — then the project's live (active) release. A release with no site files (a functions-only API) binds to the project's empty deployment; the host serves the live release's routes. 404 when the named release or operation is not this project's, or the project has never deployed. A first activation that serves site files or routes and has no `subdomains` slice claims a host automatically (derived from the project name); this route is for choosing a different name or claiming after the fact.

## Request body

- object
  - `name` string, required: Subdomain name (for example, 'myapp' for <subdomain>.run402.com)
  - `deployment_id` string: Optional target: a legacy deployment id (dpl_...), or a rel_... / op_... id the gateway resolves to the site deployment it staged. Omit both this and release_id to bind the project's live release.
  - `release_id` string: Optional release id (rel_...) whose site deployment the subdomain should bind. Omit both this and deployment_id to bind the project's live release.

## Response `201`

Subdomain created

- Subdomain
  - `name` string
  - `deployment_id` string
  - `release_id` string, nullable: On a claim response: the release the bound deployment belongs to, when the target was resolved from a release, an operation, or the live release.
  - `resolved_from` 'deployment_id' | 'release_id' | 'operation_id' | 'live_release' | 'latest_deployment', nullable: On a claim response: how the bound deployment was chosen.
  - `url` string, uri
  - `deployment_url` string, uri
  - `project_id` string: Run402 project ID. Public IDs are not UUIDs.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `404`: The project (or the named release / operation) has no site deployment to bind

---

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