Domains › Get a domain
Domains
Get a domain
GET/api/{ORG}/domains/{domain}Permalink
Answers the Domain.
- Permission
- Domains · view
- Plan
- Plans that include the API: Pricing
- Retry
- Safe: a read changes nothing
Example request
curl "https://console.brevily.com/api/NORTHWIND/domains/go.example.com" \ -H "x-api-key: brv_ak_7Fq2Lw9xK3" \ -H "x-api-secret: $BREVILY_SECRET"const res = await fetch("https://console.brevily.com/api/NORTHWIND/domains/go.example.com", { headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, },});const answer = await res.json();Example answer
{ "domain": "go.example.com", "name": "example", "shared": false, "status": "PENDING", "parent": "example", "offersSubdomains": false, "planStatus": "ACTIVE", "choiceDueOn": "2026-11-05T09:41:00Z", "isDefault": false, "purpose": "LINKS", "method": "DNS_TXT", "verifiedOn": "2026-11-05T09:41:00Z", "heldUntil": "2026-11-05T09:41:00Z", "freeOn": "2026-11-05T09:41:00Z", "certificate": { "status": "example", "issuedOn": "2026-11-05T09:41:00Z", "expiresOn": "2026-11-05T09:41:00Z" }, "records": [ { "type": "TXT", "name": "example", "value": "example", "ttl": "example" } ], "links": 1, "slugLength": 1, "slugMode": "RANDOM", "allowChosenSlugs": false, "allowSlugModeOverride": false, "defaultRedirectUrl": "https://www.example.com/sale/autumn", "notFoundRedirectUrl": "https://www.example.com/sale/autumn", "expiredRedirectUrl": "https://www.example.com/sale/autumn", "disabledRedirectUrl": "https://www.example.com/sale/autumn", "passClickIds": false, "passNames": [ "example" ], "createdOn": "2026-11-05T09:41:00Z"}{ "code": "VALIDATION_FAILED", "message": "Check the form. status: Not a value this field takes.", "details": { "fields": { "status": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values.
PathPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
ORG | string | required | Your organisation’s code. | 3 to 20 characters |
domain | string | required | — |
QueryPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
status | string | optional | Narrows the answer: ?status=<value>, or ?status=eq:<value>. | — |
add | string | optional | Narrows the answer: ?add=<value>, or ?add=eq:<value>. | — |
checked | string | optional | Narrows the answer: ?checked=<value>, or ?checked=eq:<value>. | — |
q | string | optional | A search term. | — |
sort | string | optional | One of domain, status, then :asc or :desc (?sort=domain:desc). | — |
AnswerPermalink
Domain
| Name | Type | Description | Allowed values |
|---|---|---|---|
domain | string | The hostname, lower case. | — |
name | string | The name it is listed under. | — |
shared | boolean | One of Brevily’s shared domains; false for an organisation’s own. | — |
status | string | PENDING until its DNS record proves it (a requested subdomain: until it is approved); DELETED once removed while links named it. | PENDING, VERIFIED, SUSPENDED, DELETED |
parent | string | The shared domain a requested subdomain sits under; null for any other domain. | or null |
offersSubdomains | boolean | A shared domain organisations may ask a subdomain of; false for any other domain. | — |
planStatus | string | Against the plan: serving, being chosen between, picked to stay, or switched off. | ACTIVE, CHOOSE, KEEP, PARKED |
choiceDueOn | date-time | When an open choice of the domains to keep is due; null when none is. | or null |
isDefault | boolean | The shared domain a new link lands on when none is chosen. | — |
purpose | string | LINKS, or only one kind: the short links of shared reports and public link stats (SHARES), partners’ referral links (PARTNER) or Brevily’s own campaign links (CAMPAIGN). | LINKS, SHARES, PARTNER, CAMPAIGN |
method | string | The record that proves it (that proved it, once verified): its TXT record; null when none. | DNS_TXT; or null |
verifiedOn | date-time | When it was proved; null while it has not been. | or null |
heldUntil | date-time | An unverified claim holds its name until then; null otherwise. | or null |
freeOn | date-time | A removed own domain holds its name until then; null otherwise. | or null |
certificate | Certificate | — | |
records | DnsRecord[] | The DNS records to add: the one that proves it, and the ones that connect it. | — |
links | integer | Links on it that still answer (active, disabled, expired). | — |
slugLength | integer | How long a generated back-half is now (it grows with use). | — |
slugMode | string | How generated back-halves are drawn. | RANDOM, SEQUENTIAL, SHUFFLED |
allowChosenSlugs | boolean | People may type their own back-half on it. | — |
allowSlugModeOverride | boolean | A link may pick the other generator. | — |
defaultRedirectUrl | string | Where its root sends visitors; null for the default. | or null |
notFoundRedirectUrl | string | Where an unknown back-half sends visitors; null for the default page. | or null |
expiredRedirectUrl | string | Where an expired link sends visitors; null for the default page. | or null |
disabledRedirectUrl | string | Where a disabled link sends visitors; null for the default page. | or null |
passClickIds | boolean | An own domain’s default: its links pass the ad networks’ click ids (gclid, fbclid, msclkid and the rest) from the visit, unless a link or its folder chooses for itself. True until set false. | — |
passNames | string[] | An own domain’s default: other names of the visit’s parameters its links pass on beside utm_ ones (never a redirect’s, such as next or url). | — |
createdOn | date-time | When it was added. | or null |
Fields of certificate
| Name | Type | Description | Allowed values |
|---|---|---|---|
status | string | PENDING, ISSUED or FAILED. | — |
issuedOn | date-time | When it was issued; null until it is. | or null |
expiresOn | date-time | When it expires; null until it is issued. | or null |
Fields of records
| Name | Type | Description | Allowed values |
|---|---|---|---|
type | string | The record’s type. | TXT, A, AAAA |
name | string | The name the record sits at. | — |
value | string | What it holds. | — |
ttl | string | Its time to live ("Auto": the provider’s default). | — |
ErrorsPermalink
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED |
A field, a parameter or the body is wrong; details.fields says which. |
| 401 | UNAUTHENTICATED |
No key, a key that does not match, or one expired or revoked. |
| 403 | ACCESS_DENIED |
The key lacks Domains · view, or the organisation’s plan does not include it. |
| 404 | NOT_FOUND |
No organisation with that code for this key, or no such record in it. |
| 429 | RATE_LIMITED |
Too many calls: wait Retry-After seconds. |
Rate limitsPermalink
Counted with every other call of the organisation, by plan: Pricing. The answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; more on rate limits.
Type a call, a field or a guide.