Assign branch subdomain via API

Hi there,

I have branch deploys set to all, and every new branch gets pushed to a subdomain e.g.

Navigating to domain settings -> branch subdomains -> create subdomain, and selecting a subdomain, the subdomain for the above will be created based on the branch name, e.g.

Is there a way to do this programatically via the API? I cant find any docs on it.

I’d like to use the branch subdomain feature to create mini sites, for clients (after signing up to pro plan).

The idea is to create a build, push to GIT via api, auto branch deploy created the subdomain, and the final part would be selecting the subdomain name programatically, Do you think this is a good way to go about it? I’ve read in the docs the branch deploys is for testing updates to the main site, but I think it could work for what I need here - creating subdomain sites for clients and saving as branches too.


Hiya @lemongrab!

You can’t directly create the branch subdomain; it has some prerequisites which must be satisfied before it (automatically) becomes active.

  1. your site’s main branch must have deployed successfully
  2. the branch in question must ALSO have deployed successfully on the same site, and it must NOT be the production branch
  3. the site must have a primary custom domain set.
  4. the hostname you want to use for the branch subdomain must match the pattern branchname.yourprimarycustomdomain exactly.
  5. your SSL certificate must cover that hostname. Usually this is accomplished by a wildcard SSL certificate which we should create for you automatically in case we host your DNS. If we don’t, you’ll want to upload one for yourself to cover those name(s)/

Then, you need do nothing other than use the branch subdomain! You cannot specify the name in any way; it has to match that pattern, so it’s both easier, and less flexible than you were hoping.

Thanks @fool!

All of the above is correct, but is pointing to and not the branch subdomain :S
This is after adding manually in domain alias. Would the wildcard feature sort this? I would have thought wildcard and manual entry would have worked the same?

Thanks again!

Yes, we are doing what you have configured.

Branch subdomains should NOT be set as domain aliases; domain aliases show the production deploy.

Not sure which wildcard feature you refer to, but this flow works regardless of anything wildcard set on our side.

Hi @fool

Still struggling a bit with this sorry. I’m just getting ' ’s server IP address could not be found. DNS_PROBE_FINISHED_NXDOMAIN ’

Here’s what I’ve done, is there something I’m missing?

  1. main branch deployed successfully
  2. branch in question deployed successfully (
  3. primary domain is set (
  4. branch name matches the host name I want to use - site6 (
  5. using Netlify DNS, wildcard SSL automatically created

From what I understand, should work now? But it doesn’t exist.
It does exist in the branch subdomain section within settings , and only shows live at if I click ‘new subdomain’ and select site6. I’m trying to avoid this manual step.


Ah, I think this is because I don’t actually have wildcard SSL automatically created? If this is the case, please could you add this for me? I’ve upgraded my plan.

Thanks again

  1. Either you have to use Netlify DNS so we can get you a wildcard SSL cert, or you must bring a custom wildcard certificate.
  2. We can only do this for a site that’s on a paid team (see for details).

Hmm, I see a wildcard certificate there already:

I apologize - I somehow did not realize you were using netlify DNS so some of my instructions were assuming the opposite. However, you’re super close and can self-serve the rest of the way:

from here, create all the branch subdomains you want:

…and we’ll then automatically create DNS records for you, which you’ll be able to see here.

If you have external DNS rather than ours, you’d have to create those records manually, and you can here, but better to use our UI since it’ll do everything correctly for you here :slight_smile:

Thanks @fool, no problem!

I’m trying to get this whole thing wrapped up programatically, without having to click on the subdomain within settings (screenshot)

As you can see, there’s ‘site6’ listed within the branch subdomains right now.

How would I get activated as a subdomain from here and working to show site6 content without visiting settings?

As mentioned, I cant find a way to do it after looking through the API docs.


you would click on it in that list.

Using the methods in this article:

…you would have the browser dev tools open to see the API calls our frontend makes, and from those, you would craft your own similar calls to achieve your purposes programatically in the future.

You aren’t missing anything; there are no more specific docs for that use case :slight_smile: