---
title: "Adds a domain to the specified site instance."
method: PUT
path: "/site-instances/{siteId}.{environmentId}/domains/{domainName}"
tags: ["Domains"]
---

# Adds a domain to the specified site instance.

`PUT /site-instances/{siteId}.{environmentId}/domains/{domainName}`

## Request

- Base URL: `https://api.acquia.com/v3`
- URL: `https://api.acquia.com/v3/site-instances/{siteId}.{environmentId}/domains/{domainName}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/acquia/apis/acquia-cloud-platform-api/docs/site-instances/:siteId.:environmentId/domains/:domainName/put.ts> (a function with typed inputs; its response is checked against the schema)

Adds a domain to the specified site instance. Accepts a JSON body whose `type` property is optional, defaulting to `custom` when omitted or when the body is `{}`; a request with no body at all is treated as `{}`. `type: launch-group` marks the domain as belonging to a launch group rather than to the site instance directly, and is restricted to Acquia staff — a non-elevated caller's request is rejected with `403`. Domains of this type are still returned in standard domain listings, and traffic continues to route to them. Adding a domain under an Acquia-reserved domain suffix (e.g. `acquia-sites.com`) is restricted to Acquia staff, as is adding a path-based domain; either is rejected with `403` for a non-elevated caller.

## Path parameters

- `siteId` string, required
- `environmentId` string, required
- `domainName` string, required

## Request body

- object
  - `type` 'custom' | 'launch-group': Optional. The type to register the domain under, defaulting to `custom` when omitted. `launch-group` marks the domain as belonging to a launch group rather than to the site instance directly; it is restricted to Acquia staff, and is rejected with `403` for any other caller. The three platform-owned types — `acquia`, `environment-pattern`, `codebase-pattern` — are read-only and rejected with `400` if requested here.

## Response `202`

Domain addition started

- object
  - `_links` object, required: HAL links for the resource
    - `self` EnvironmentServiceAPIHalLink, required: HAL link object
      - `href` union, required: The target URI of the link (can be a URI or URI template)
        - string, uri
        - string, uri-template
      - `templated` boolean: Whether the link is a URI template
      - `type` string: Hint about the media type expected when dereferencing the target resource
      - `deprecation` string: A URL to a resource that provides deprecation information
      - `name` string: A secondary key for selecting links
      - `profile` string: A URI that hints about the profile of the target resource
      - `title` string: A human-readable identifier for the link
      - `hreflang` string: The language of the target resource
  - `_embedded` object: Embedded resources (optional)
  - `message` 'Domain addition started.', required: Confirmation message that the domain addition has been started.

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error

---

[API](https://skmtc.dev/acquia/apis/acquia-cloud-platform-api.md) - [All operations](https://skmtc.dev/acquia/apis/acquia-cloud-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/acquia/apis/acquia-cloud-platform-api/revisions/508f8f94456d?raw)