Skip to main content
A custom domain lets you serve Awardee content from a hostname you own — acme.com, support.acme.com, docs.acme.com — instead of the default *.awardee.dev URLs. Customers see your brand, links stay short, and email/share previews carry your domain. A connected domain on its own doesn’t route anything. You attach one or more Custom Domain Routes to map paths on the domain to specific chatbots, knowledge bases, or pages.
Custom domains are a paid add-on. Each connected hostname adds one unit of the custom_domain add-on to your subscription, prorated by Stripe. The number of domains per organization is not capped — billing is per-slot.

​
Lifecycle

1

Connect

POST /custom-domains with { "domain": "acme.com" }. We register the hostname with the TLS terminator and return a list of DNS records you need to publish.
2

Publish DNS

Add each record in verification_records at your DNS provider. Apex domains use an A record (76.76.21.21); subdomains use a CNAME to cname.vercel-dns.com. Some domains also need a TXT record for ownership.
3

Verify

Once DNS has propagated (5 minutes to ~24 hours depending on the provider), call POST /custom-domains/{id}/verify. When it returns status: "verified", the TLS cert provisions automatically and traffic starts flowing.
4

Route

Attach one or more routes so paths on the domain resolve to your content.
Apex domains (acme.com) are auto-paired with a www.acme.com 308 redirect — visitors to either form land on the canonical apex without you doing anything. Subdomains are not paired.

​
Connect a domain

cURL
curl https://api.awardee.dev/v1/custom-domains \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com" }'
Response
{
  "object": "custom_domain",
  "id": "2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d",
  "domain": "acme.com",
  "verified": false,
  "verified_at": null,
  "last_checked_at": null,
  "check_error": null,
  "verification_records": [
    {
      "type": "A",
      "domain": "acme.com",
      "value": "76.76.21.21",
      "reason": "pending_domain_verification"
    }
  ],
  "created_at": "2026-05-25T11:00:00+00:00"
}
POST /custom-domains accepts an Idempotency-Key header so retries are safe. See Idempotency.
The domain must be a syntactically valid hostname. An invalid value (malformed host, an embedded path or scheme, illegal characters) is rejected with 422 and the message “The domain is not a valid hostname.” The check is provider-agnostic — Awardee validates the hostname itself and does not surface upstream registrar or DNS details.

​
Verify

DNS changes can take a few minutes to a few hours to propagate. Once you’ve published the records, ask the API to re-check:
cURL
curl -X POST https://api.awardee.dev/v1/custom-domains/2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d/verify \
  -H "Authorization: Bearer aw_live_…"
Response (still pending)
{
  "object": "custom_domain_verification",
  "status": "pending",
  "domain": {
    "object": "custom_domain",
    "id": "2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d",
    "domain": "acme.com",
    "verified": false,
    "last_checked_at": "2026-05-25T11:02:14+00:00",
    "verification_records": [ ... ]
  }
}
Response (success)
{
  "object": "custom_domain_verification",
  "status": "verified",
  "domain": {
    "object": "custom_domain",
    "id": "2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d",
    "domain": "acme.com",
    "verified": true,
    "verified_at": "2026-05-25T11:08:42+00:00",
    "last_checked_at": "2026-05-25T11:08:42+00:00",
    "verification_records": []
  }
}
status is one of:
ValueMeaning
verifiedOwnership confirmed, DNS pointing at us, TLS cert provisioning. Domain is live.
pendingDNS hasn’t propagated yet — wait and retry. This is the normal greenfield state.
errorThe check itself failed (e.g. upstream timeout). error carries the reason.
We also poll verification automatically every few minutes for the first hour after connect, so a domain often flips to verified without you calling the endpoint. You can still call it manually to force an immediate re-check.

​
List

cURL
curl https://api.awardee.dev/v1/custom-domains \
  -H "Authorization: Bearer aw_live_…"
Supports page, page_size, and search (substring match on domain).

​
Disconnect

DELETE /custom-domains/{id} removes the hostname from the TLS terminator, deletes the row, and releases the billable add-on slot. All custom_domain_routes attached to the domain are removed by the FK cascade.
cURL
curl -X DELETE https://api.awardee.dev/v1/custom-domains/2c8a4d6f-1e3b-4d5a-9b7c-8e1f2a3b4c5d \
  -H "Authorization: Bearer aw_live_…"
Returns 204 No Content.
Disconnecting takes the domain offline immediately. Any inbound traffic from that point on falls through to whatever your DNS now points at — usually a 404 from the previous CNAME target.

​
Permissions

Endpoints under /custom-domains require these scopes when called with an OAuth access token. Personal API keys are unscoped — they bypass these checks.
EndpointRequired scope
POST /custom-domainsdomains.manage
GET /custom-domainsdomains.view
GET /custom-domains/{id}domains.view
DELETE /custom-domains/{id}domains.manage
POST /custom-domains/{id}/verifydomains.manage