List DNS records — Brigg developers

Access & visibility

Allow domains.ListDnsRecords on your API key.

Acting member required. Send Brigg-Act-As with an approved member account ID. The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

idstringRequired

Use the hosted domain's id, not its hostname. domains.ListHostedDomains.

At least 1 character. At most 80 characters.

Read the hosted zone

Select the domain's id from List hosted domains. The domain must be active and DNS-hosted by Brigg. The response lists stored zone records; it is not a recursive DNS lookup and does not show what every external resolver currently caches.

Record names are relative to zone: @ is the apex and www is a subdomain. TTL is in seconds; values contains the complete value set for that name/type pair. An alias can use alias.target instead of ordinary values. When preparing a change with Set DNS record, use @ for the apex or a relative name such as www and include every value you want to keep. Brigg-managed zone records, website aliases and certificate records are excluded. Use the website connection operations to manage site aliases.

Response

Returns 200 OK with a JSON body.

This operation has no continuation cursor. An empty items array means no matching visible results were returned.

zonestringRequired

Hosted DNS zone for these records.

itemsarray of DNS recordRequired

DNS records in the selected hosted domain's zone. This operation has no cursor pagination.

Item fields

namestringRequired

Relative DNS name within zone: @ is the apex, www is the www subdomain.

typestringRequired

DNS record type, such as A, CNAME, MX or TXT.

Allowed: "A", "AAAA", "CNAME", "MX", "TXT".

ttlnumberRequired

Time to live in seconds; resolvers may cache this record for this duration.

valuesarray of stringRequired

Record values in the format required by type. MX values include priority; TXT values contain the text value.

aliasobjectOptional

Alias-target configuration when this is an alias record; ordinary records use values.

Nested fields

targetstringRequired

DNS target hostname for this alias.

Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying.
409	`not_hosted`	The domain must be active with a hosted DNS zone. Inspect ListHostedDomains before retrying.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Use the hosted domain's id, not its hostname. [domains.ListHostedDomains](/developers/reference/domains/ListHostedDomains)."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "id": "domain_example"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "zone": {
      "type": "string",
      "description": "Hosted DNS zone for these records."
    },
    "items": {
      "type": "array",
      "items": {
        "title": "DNS record",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Relative DNS name within zone: @ is the apex, www is the www subdomain.",
            "examples": [
              "www"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "A",
              "AAAA",
              "CNAME",
              "MX",
              "TXT"
            ],
            "description": "DNS record type, such as A, CNAME, MX or TXT.",
            "examples": [
              "CNAME"
            ]
          },
          "ttl": {
            "type": "number",
            "description": "Time to live in seconds; resolvers may cache this record for this duration.",
            "examples": [
              3600
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Record values in the format required by type. MX values include priority; TXT values contain the text value.",
            "examples": [
              [
                "sites.example.net"
              ]
            ]
          },
          "alias": {
            "type": "object",
            "properties": {
              "target": {
                "type": "string",
                "description": "DNS target hostname for this alias."
              }
            },
            "required": [
              "target"
            ],
            "additionalProperties": false,
            "description": "Alias-target configuration when this is an alias record; ordinary records use values."
          }
        },
        "required": [
          "name",
          "type",
          "ttl",
          "values"
        ],
        "additionalProperties": false
      },
      "description": "DNS records in the selected hosted domain's zone. This operation has no cursor pagination."
    }
  },
  "required": [
    "zone",
    "items"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "zone": "example.com",
      "items": [
        {
          "name": "www",
          "type": "CNAME",
          "ttl": 3600,
          "values": [
            "sites.example.net"
          ]
        }
      ]
    }
  ]
}

Try the request

Use your API key in a server environment.

Requires BRIGG_ACT_AS: an approved member account ID.

Fictional values. Replace IDs and business details with values from your workspace.

Request

cURL

curl 'https://api.brigg.app/v1/operations/domains.ListDnsRecords' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "id": "domain_example"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/domains.ListDnsRecords", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "id": "domain_example"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "id": "domain_example"
}
request = Request(
    "https://api.brigg.app/v1/operations/domains.ListDnsRecords",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "zone": "example.com",
  "items": [
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 3600,
      "values": [
        "sites.example.net"
      ]
    }
  ]
}

Illustrative values, not a live response.