Available Domains
List the domains the calling user can use when creating an endpoint. The list combines two sources: shared platform domains (e.g. ngris.io, ngris.dev) accessible to everyone on the right plan, and custom domains the user owns (registered via POST /v1/domains/self).
Account scope: custom domains here are those of your active account, shared with its members per your role's permissions. Use switch account to work with a different account's domains.
Permissions: any member of the active account can call it, so every member can pick a domain when creating an endpoint; it never answers 403. What each item carries depends on the domains:read permission:
- With
domains:read(the account owner, and any role that has it): every field in the table below. - Without it: a reduced item with only
uuid,name,account_uuid(your account's own domains only, as in the full item),plan_access,provisioning_mode(so you know whether ngris creates an endpoint's DNS record or it rides your wildcard CNAME),system_managed,is_active,statusandcert_expiry. It has no DNS provider, provider settings, creator, certificate status or issuer, issuance state, registration or expiry suspension.
The list is the same in both cases: the same domains in the same order, with the same include_inactive and paging.
Use this to populate the domain dropdown when provisioning a new endpoint. The uuid returned here is what you pass as domain_uuid to POST /v1/endpoints.
By default only active domains are listed. Pass include_inactive=1 to also list your account's switched-off custom domains — for example one suspended because its registration expired (the dashboard's Domains page uses this).
Query parameters
include_inactive string
1 (or true) also returns the account's custom domains that are switched off (is_active: false). Omit it for active domains only (the default).page_size int
Domains per page. Omit it (the default) to get every domain in one response.
page int
1-based page number, used with
page_size. Default 1.Response (200 OK)
items object[]
The domains: your account's own custom domains first, then the shared platform domains your plan can use, each group by name.
[] when there are none.page int
The page returned (
1 when page was not sent).page_size int
The page size;
0 when page_size was not sent (every domain returned).total int
Number of domains across all pages.
Each domain has the fields below when you have domains:read. Without it you get only the reduced item described under Permissions above.
uuid string (uuid)
The domain's uuid. Pass it to POST /v1/endpoints as
domain_uuid; custom domains also use it in paths like /domains/self/{uuid}.name string
Fully-qualified domain (e.g.
example.com).created_by_uuid string (uuid)?
The user who created this domain (provenance) — not the owner. The owner is
account_uuid. Omitted when unset, and never sent for a shared platform domain (system_managed: true). Do not use this to detect platform domains; use system_managed.account_uuid string (uuid)?
The owning account of a custom domain. Omitted when the domain has no owning account.
system_managed boolean
Authoritative flag for "is this a platform/shared domain".
true for the platform's own domains and admin-provisioned shared domains (under which you pick a subdomain); false for a custom domain you registered.provider string
DNS provider for custom domains (
cloudflare, route53, digitalocean, cpanel, webmin, namecheap, or none). Always none on platform-shared domains.is_active boolean
Whether the domain is verified and ready to host endpoints. Newly-added custom domains are
false until DNS verification completes.provisioning_mode string
How the domain's DNS records are managed:
auto (ngris holds your DNS provider credentials, writes the records and issues the wildcard certificate), manual (you added the CNAME at your provider; ngris only validates it) or wildcard (a wildcard CNAME already points at ngris, so per-endpoint records are skipped; ngris still issues the certificate).provider_config string
Your custom domain's DNS provider settings as a JSON string, with the secret fields (
api_token, password, secret, secret_access_key, api_key) blanked, e.g. {"api_token":"","zone_id":"…"}. "" on shared platform domains and when none is set.status string
The domain's certificate issuance state:
pending_issuance, issuing, active, issuance_failed, renewal_failed or revoked; expired while a custom domain is suspended for an expired registration (see expiry_suspension).issuance_error string?
Why the last certificate issuance failed. Omitted when unset.
last_issuance_at datetime?
When a certificate was last issued for the domain. Omitted when none was.
cert_status string?
The domain's current default certificate:
issued, expiring (within 30 days), expired, or none when it has no active certificate. Omitted if the certificate lookup failed.cert_expiry datetime?
When that certificate expires. Omitted when there is none.
cert_issuer string?
The certificate issuer's organisation (e.g.
Let's Encrypt). Omitted when unknown.quota_paused_at datetime?
Set while your custom domain is paused because the account has more custom domains than its plan allows: kept, but not served. Omitted otherwise.
created_at, updated_at datetime
RFC 3339 UTC timestamps.
plan_access string
all | plan-restricted. Restricted shared domains are only available on certain paid plans.expires_at datetime?
Custom domains: the domain's registration expiry — the date the expiry reminders use, read for every custom domain whatever its DNS provider (Cloudflare Registrar, RDAP or WHOIS; see
registration). During a registry's auto-renew grace it stays the old date. Omitted when unknown. Not the TLS certificate's expiry (that is cert_expiry).expiry_suspension object?
Present only while the domain is suspended because its registration expired (
status: "expired", is_active: false — so it is listed only with include_inactive=1). See the expiry_suspension object and Check again.registration object?
Your account's own custom domains only: the domain's registration as last looked up —
expires_at, source (rdap | whois | cloudflare), statuses (the registry's EPP statuses), not_renewed_status (e.g. auto renew period: the registry's date isn't a paid renewal yet), checked_at and lookup_error (why the last lookup failed). Field by field: the registration object. Absent on shared platform domains, and while registration lookups aren't enabled on the platform yet. The same object is on each item of GET /v1/domains/self (the account's own domains).Deprecated: until the sunset this response also carries the legacy integer id, created_by and account_id fields (the reduced item carries only id and account_id; a shared platform domain never carries created_by). Don't use them; read uuid, created_by_uuid and account_uuid.
Errors
401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/domains/available" \
-H "X-API-KEY: <your_api_key>"
Request — include switched-off domains
curl "https://api.ngris.com/v1/domains/available?include_inactive=1" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
for d in client.domains.list_available()["items"]:
badge = "(shared)" if d["system_managed"] else "(yours)"
print(f"{d['name']} {badge}")
Response — 200 OK
{
"items": [
{
"uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"name": "example.com",
"created_by_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"plan_access": "all",
"provider": "cloudflare",
"provider_config": "{\"api_token\":\"\",\"zone_id\":\"0a1b2c3d4e5f60718293a4b5c6d7e8f9\"}",
"provisioning_mode": "auto",
"is_active": true,
"system_managed": false,
"expires_at": "2027-03-14T00:00:00Z",
"status": "active",
"last_issuance_at": "2026-08-02T06:10:00Z",
"created_at": "2026-03-14T09:20:00Z",
"updated_at": "2026-08-02T06:10:00Z",
"cert_status": "issued",
"cert_expiry": "2026-10-31T06:10:00Z",
"cert_issuer": "Let's Encrypt",
"registration": {
"expires_at": "2027-03-14T00:00:00Z",
"source": "cloudflare",
"statuses": [],
"checked_at": "2026-10-19T08:05:40Z"
}
},
{
"uuid": "019a400d-c107-7f74-a3d3-0a79d92b0703",
"name": "ngris.dev",
"plan_access": "all",
"provider": "none",
"provider_config": "",
"provisioning_mode": "wildcard",
"is_active": true,
"system_managed": true,
"status": "active",
"created_at": "2026-01-10T00:00:00Z",
"updated_at": "2026-09-01T00:00:00Z",
"cert_status": "issued",
"cert_expiry": "2026-12-01T00:00:00Z",
"cert_issuer": "Let's Encrypt"
}
],
"page": 1,
"page_size": 0,
"total": 2
}
Response — a member without domains:read
{
"items": [
{
"uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"name": "example.com",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"plan_access": "all",
"provisioning_mode": "auto",
"system_managed": false,
"is_active": true,
"status": "active",
"cert_expiry": "2026-10-31T06:10:00Z"
},
{
"uuid": "019a400d-c107-7f74-a3d3-0a79d92b0703",
"name": "ngris.dev",
"plan_access": "all",
"provisioning_mode": "wildcard",
"system_managed": true,
"is_active": true,
"status": "active",
"cert_expiry": "2026-12-01T00:00:00Z"
}
],
"page": 1,
"page_size": 0,
"total": 2
}
A suspended domain (include_inactive=1)
{
"uuid": "019bd7f0-adb4-7951-b51e-c13fab0a1443",
"name": "example.net",
"system_managed": false,
"provider": "cloudflare",
"is_active": false,
"status": "expired",
"expires_at": "2026-09-28T00:00:00Z",
"expiry_suspension": {
"suspended_at": "2026-09-28T00:05:12Z",
"expires_at": "2026-09-28T00:00:00Z",
"deletes_at": "2026-10-28T00:05:12Z",
"recheck_interval_hours": 4,
"check_again_available": true,
"check_state": "idle",
"last_checked_at": "2026-09-30T08:05:40Z",
"last_check_outcome": "still_expired"
},
"registration": {
"expires_at": "2026-09-28T00:00:00Z",
"source": "cloudflare",
"statuses": [],
"checked_at": "2026-09-30T08:05:40Z"
}
}
A domain whose last registration lookup failed
{
"uuid": "019be7f9-a715-702f-a9cc-6ecd79428f98",
"name": "example.dev",
"system_managed": false,
"provider": "none",
"is_active": true,
"status": "active",
"registration": {
"expires_at": null,
"statuses": [],
"checked_at": "2026-09-30T07:41:02Z",
"lookup_error": "the registry has no record of this domain"
}
}
Was this helpful?