# Put app. and api. subdomains on different projects

> Point subdomains like app. and api. to different projects in one command using account-level domains, with automatic HTTPS and zero manual DNS.

**To point subdomains like `app.` and `api.` to different projects, assign each prefix to its target project using `vibiz domains use`.** When you buy a domain through thelastapi, it belongs to your account rather than an individual project. Our nameservers handle routing and TLS provisioning automatically, so you do not need to configure manual DNS records or wait for third-party propagation.

This guide walks through configuring multiple subdomains across separate projects, routing external hosts, and reassigning names when your architecture evolves.

## How account-level domains work

In many setups, a custom domain is tightly bound to a single application repository or container. If you want `api.example.com` to reach a backend service while `app.example.com` routes to a frontend interface, you normally have to log into an external registrar, create individual `CNAME` records, and set up separate SSL certificate verifications.

On thelastapi, domains function at the account level:

- **Central ownership:** A bought domain is owned by your account. Any project in your account can use the apex domain, a prefix (`app`), or a nested name (`v1.api`).
- **No manual DNS for our hosting:** When an app uses thelastapi hosting, assigning a subdomain provisions an HTTPS certificate automatically. The domain status never gets stuck on `pending_dns`, `records_to_set` remains empty, and `dns_by_vibiz` is set to `true`.
- **Isolation:** Each name routes to exactly one project at a time. This prevents conflicting traffic while letting you split backends, frontends, and documentation into distinct projects with isolated logs, databases, and environment variables.

If you are setting up the legal structure behind these projects, you can also handle registration in your terminal. See [what it costs to form a US company: state fees plus one service fee](https://thelastapi.dev/blog/cost-to-form-us-company) or review [LLC vs C-Corp for a SaaS: what to think about (not legal advice)](https://thelastapi.dev/blog/llc-vs-c-corp-saas). Complete filing specifications are documented under [Company formation](https://thelastapi.dev/docs/company).

## How to point subdomains to separate projects

Suppose you have a domain called `sellshelf.app` and two distinct projects:
1. `sellshelf-web` (your user interface)
2. `sellshelf-backend` (your API server)

### 1. Check your available projects and domains

First, list the domains registered to your account to confirm ownership:

```bash
vibiz domains owned
```

This returns JSON or tabular output displaying the domain name, registration expiration, auto-renewal status, and any active routing targets.

### 2. Point `app.` to the frontend project

To point `app.sellshelf.app` to your frontend project, run the `use` command with the `--name` flag:

```bash
vibiz domains use sellshelf.app --project sellshelf-web --name app
```

You can also pass the full subdomain directly:

```bash
vibiz domains use app.sellshelf.app --project sellshelf-web
```

Both commands tell our nameservers to route requests for `app.sellshelf.app` to `sellshelf-web`. Within a minute or two, the subdomain becomes active and HTTPS certificates are provisioned.

### 3. Point `api.` to the backend project

Next, map `api.sellshelf.app` to your backend project:

```bash
vibiz domains use sellshelf.app --project sellshelf-backend --name api
```

Now, `app.sellshelf.app` and `api.sellshelf.app` point to entirely separate projects, each with their own logs, compute resources, and environment settings.

### Doing it over HTTP

If your deployment pipeline or agent handles routing, you can make an HTTP request to `/v1/domains/:domain/use`:

```bash
curl -X POST "https://thelastapi.dev/v1/domains/sellshelf.app/use" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_backend_123",
    "name": "api"
  }'
```

The API returns a `domain_use` object confirming that the domain was attached without requiring any manual `records_to_set`. For more details on API parameters, check the [Domains](https://thelastapi.dev/docs/domains) documentation.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The ID or slug of the project receiving the subdomain. |
| `name` | string | No | The subdomain prefix (e.g., `app`, `api`) or `@` for apex. |
| `hosting` | string | No | Defaults to thelastapi hosting. Pass `elsewhere` for external hosts. |
| `points_to` | string | No | Target IP address or hostname if `hosting` is external. |

## How to route a subdomain to an external host

Not every project lives on the same infrastructure. If your API runs on an external server while your main app runs on thelastapi, you can still manage the routing from the same domain without leaving your CLI.

Pass the `--elsewhere` flag along with `--points-to`:

```bash
vibiz domains use sellshelf.app \
  --project sellshelf-backend \
  --name api \
  --elsewhere \
  --points-to "api-server.externalhost.com"
```

Our nameservers write the DNS record automatically:
- A `CNAME` is created for subdomains like `api`.
- An `ALIAS` (or `A` record for IPv4) is created if you point the apex domain.

If the external server address changes, update it with `vibiz domains point`:

```bash
vibiz domains point api.sellshelf.app api-v2.externalhost.com
```

To clear an external target and return to default behavior, run:

```bash
vibiz domains point api.sellshelf.app none
```

## How to move a subdomain between projects

Because a subdomain serves only one project at a time, pointing an existing subdomain to a new project with `vibiz domains use` will fail with an error:

```text
HTTP 409 Conflict: in_use
```

The error details name the project currently using that subdomain. To reassign a subdomain from an old service to a new one, use `vibiz domains move` (which requires a full-access key):

```bash
vibiz domains move sellshelf.app --name app --to sellshelf-web-v2
```

You can optionally include `--from` to assert which project currently holds the subdomain:

```bash
vibiz domains move sellshelf.app --name app --from sellshelf-web --to sellshelf-web-v2
```

This detaches the subdomain from `sellshelf-web` and maps it to `sellshelf-web-v2`, migrating traffic and renewing routing rules without DNS downtime.

Over HTTP, use the move endpoint:

```bash
curl -X POST "https://thelastapi.dev/v1/domains/sellshelf.app/move" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app",
    "from_project_id": "prj_web_old",
    "to_project_id": "prj_web_new"
  }'
```

## Inspecting your active routes and records

To see which projects and subdomains are connected to your domains, run:

```bash
vibiz domains owned
```

The command returns the domain status, auto-renewal flag, and an array of `used_on` entries detailing each project, prefix, and hosting status.

If third-party tools ask you to verify domain ownership (such as an OpenAI business profile or search console records), you can add manual DNS entries alongside your routing rules:

```bash
vibiz domains records add sellshelf.app TXT verify "verification-code-value"
```

To inspect all DNS records for a domain:

```bash
vibiz domains records sellshelf.app
```

Records managed by our hosting or email services are labeled `managed`. You cannot accidentally overwrite or remove a managed record; attempting to delete one returns a `409 managed_record` error unless you pass the `--force` flag.

## Structuring projects for your business

Dividing your frontend, API, and microservices across distinct projects helps keep permissions and environment variables tidy. If these projects form part of a new venture, you can register the underlying company from the same interface. Explore [Form a US LLC or C-Corp from your terminal: costs and steps](https://thelastapi.dev/blog/form-us-llc-c-corp-terminal) for a complete breakdown of filing options, fees, and state choices.

Next: search for a name using `vibiz domains search <name>`, or attach an existing purchase across your environments using `vibiz domains use`.

## Frequently asked questions

### Can I use the same subdomain on two different projects at the same time?

No, a subdomain serves exactly one project at a time. Attempting to assign an existing subdomain to another project returns a 409 conflict error; use `vibiz domains move` with a full-access key to reassign it.

### Do I have to create DNS CNAME records manually when using subdomains on thelastapi?

No, when you point a subdomain to a project using our hosting, our nameservers write and maintain the records automatically. HTTPS certificates are issued on attachment without manual DNS configuration.

### What happens if my app is hosted on an external server instead of thelastapi?

You can pass `--elsewhere` and `--points-to <host or IP>` to `vibiz domains use`. Our DNS automatically provisions a CNAME record for subdomains or an ALIAS/A record for apex domains to direct traffic to your external server.

### Can an agent buy and assign subdomains to projects?

Agents with limited keys can attach existing owned domains to projects using `vibiz domains use`, but buying domains or running `vibiz domains move` requires a full-access key or an explicit agent spending limit set by the account owner.

---

Published 2026-11-15 · https://thelastapi.dev/blog/subdomain-for-app-api
