Custom domains for Neon Functions

Each Neon Function has a native invocation URL. You can also serve it from a domain you own, such as api.example.com. Neon routes the custom domain to one function on one branch and provisions its TLS certificate automatically. You don't need to change your function code.

For example, one function is reachable at both URLs:

Native:  https://br-cool-forest-a1b2c3d4-api.compute.c-2.us-east-2.aws.neon.tech
Custom:  https://api.example.com

Custom domains are branch-scoped: a domain registered on one branch isn't inherited by its child branches, and each hostname can be registered only once. Use a distinct hostname for each preview or development branch.

Neon Functions do not support hosting websites.

You need:

• A deployed Neon Function.
• A domain you control, and access to its DNS settings.
• Optional: The latest Neon CLI, if you want to manage the domain from the command line.
• Optional: @neon/sdk 5.0.0 or later, if you want to manage the domain with the SDK.

neon functions domains register api.example.com --slug api --output json

{
  "domain": "api.example.com",
  "entity_type": "function",
  "entity_id": "api",
  "cname_target": "fn-custom-domains.us-east-2.aws.neon.tech",
  "status": "pending",
  "dns_status": "pending",
  "binding_status": "pending",
  "status_reason": ""
}

import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { data: domain, error } =
  await neon.functions.customDomains.register({
    projectId,
    branchId,
    domain: 'api.example.com',
    entity_type: 'function',
    entity_id: 'api',
  });

if (error) throw error;
console.log(domain.cname_target);

curl -X POST \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "api.example.com",
    "entity_type": "function",
    "entity_id": "api"
  }'

entity_type is function, the only supported value today. The function is identified by its slug: the CLI --slug flag and the API entity_id field carry the same value. Re-registering the same domain for the same function returns the same result. Registering a domain already assigned to another target returns a conflict without revealing the existing owner.

If you manage the branch with a neon.ts policy, declare the domain on the function instead of registering it imperatively. Add customDomains to the function and run neon deploy:

import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    api: {
      name: "API",
      source: "./functions/api.ts",
      customDomains: ["api.example.com"],
    },
  },
});

neon deploy

neon deploy registers the domain and prints the CNAME target to configure below. The static customDomains list applies on the default branch only, since a hostname is globally unique and can't be inherited by child branches. Removing a domain from neon.ts doesn't delete its registration; delete it explicitly, as described in Delete a custom domain. For per-branch overrides and the full ruleset, see the neon.ts reference.

At your DNS provider, create a CNAME record using the target returned during registration:

• Type: CNAME
• Name: Your custom domain, such as api.example.com. Some providers expect only the host label, such as api.
• Value: Copy the exact cname_target hostname returned by Neon, such as fn-custom-domains.us-east-2.aws.neon.tech. Don't include https:// or a URL path.
• TTL: Your provider's default.

Configure the record as DNS-only. If your provider proxies the record, Neon can't validate the domain. On Cloudflare, set the record to "DNS only" (grey cloud), not "Proxied" (orange cloud).

Remove conflicting A, AAAA, or CNAME records for the same hostname. DNS changes can take time to propagate according to the record's TTL.

neon functions domains list --output json

[
  {
    "domain": "api.example.com",
    "entity_type": "function",
    "entity_id": "api",
    "cname_target": "fn-custom-domains.us-east-2.aws.neon.tech",
    "status": "active",
    "dns_status": "ok",
    "binding_status": "present",
    "status_reason": ""
  }
]

import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { data: domains, error } =
  await neon.functions.customDomains.list({ projectId, branchId }).all();

if (error) throw error;
console.log(domains);

curl \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains" \
  -H "Authorization: Bearer $NEON_API_KEY"

Each domain reports a top-level status, plus the dns_status and binding_status that feed it.

status is:

• pending: Neon is still checking DNS or completing internal routing setup.
• active: DNS points to the Neon edge, CAA permits Let's Encrypt, and internal routing is in place.
• error: DNS, CAA, or internal routing needs attention. Check status_reason.

dns_status is pending, ok, misconfigured (resolves somewhere other than the Neon edge), or caa_blocked (a CAA record forbids Let's Encrypt). binding_status is pending, present, or missing, where missing is an internal fault.

When status is error, status_reason names the cause and its fix:

Status checks run asynchronously. Poll the domain every few seconds until it becomes active or reports an actionable error.

A request through a custom domain preserves its method, path, query, body, normal application headers, and streaming behavior. WebSockets and SSE work through the custom URL without additional configuration.

Inside the function, Request.url and the Host header use the function's native Neon hostname, not the custom hostname. To read the hostname the client requested, use the x-forwarded-host header; Neon overwrites any client-supplied value, so it's safe to trust for tenant routing.

When your neon.ts declares the function, neon env pull writes its native URL as NEON_FUNCTION_<SLUG>_BASE_URL. Store the custom URL separately in your application configuration.

If a browser calls the custom domain directly, configure CORS and authentication for that origin.

Remove the DNS record before releasing the domain registration. This prevents a dangling CNAME from continuing to point at Neon's custom-domain edge.

1. Remove the CNAME record at your DNS provider.
2. Wait for public DNS to stop returning the Neon target. Check with dig +short api.example.com.
3. Delete the registration using one of the following methods.

neon functions domains delete api.example.com

import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { error } = await neon.functions.customDomains.delete({
  projectId,
  branchId,
  domain: 'api.example.com',
});

if (error) throw error;

curl -X DELETE \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains/api.example.com" \
  -H "Authorization: Bearer $NEON_API_KEY"

Routing changes take a short time to apply everywhere. Requests can continue reaching the old function briefly after deletion, so verify that the custom URL no longer serves it before reassigning the hostname.

Deleting a function doesn't remove its custom-domain registration. Remove the domain explicitly when deleting a function.

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.