Manage Domains with the Public API
Here are examples to help you manage domains using the Public API.
List domains for a service
Get all domains (both Railway-provided and custom) for a service:
Service domains (*.railway.app)
Create a service domain
Generate a Railway-provided domain:
Delete a service domain
Custom domains
Check domain availability
Check if a custom domain can be added:
Add a custom domain
The routing DNS records are returned in status.dnsRecords. Query status.verificationToken as well to get the verification TXT token required to complete setup.
Get custom domain status
Check DNS configuration status:
Update a custom domain
Delete a custom domain
DNS configuration
After adding a custom domain, you need to configure DNS records. The routing record is returned in status.dnsRecords, while the verification TXT token is returned separately in status.verificationToken. Both are required. Without the TXT record, the domain remains pending setup and does not verify.
For root domains (example.com)
Add a CNAME-flattened, ALIAS, or ANAME record (depending on what your DNS provider supports) pointing to your Railway service domain, plus the TXT record using the token returned in status.verificationToken. Railway does not publish a static IP, so A records are not supported. See Adding a root domain for provider-specific guidance.
For subdomains (api.example.com)
Add a CNAME record pointing to your Railway service domain, plus the TXT record using the token returned in status.verificationToken.
DNS record statuses
| Status | Description |
|---|---|
PENDING | DNS record not yet configured |
VALID | DNS record is correctly configured |
INVALID | DNS record is configured incorrectly |
Certificate statuses
| Status | Description |
|---|---|
PENDING | Certificate is being issued |
ISSUED | Certificate is active |
FAILED | Certificate issuance failed |