List Domains

Returns every domain the calling key or user can access.

curl --request GET \
  --url https://api.aiclicks.io/api/v1/domains \
  --header 'Authorization: Bearer ak_live_xxx'

import httpx, os

resp = httpx.get(
    "https://api.aiclicks.io/api/v1/domains",
    headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for item in resp.json()["data"]["items"]:
    if "domains" in item:            # master key: item is a team
        for d in item["domains"]:
            print(item["team_name"], d["id"], d["website"])
    else:                            # team key: item is a domain
        print(item["id"], item["website"])

const resp = await fetch("https://api.aiclicks.io/api/v1/domains", {
  headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
for (const item of data.items) {
  if (item.domains) {                // master key: item is a team
    for (const d of item.domains) console.log(item.team_name, d.id, d.website);
  } else {                           // team key: item is a domain
    console.log(item.id, item.website);
  }
}

{
  "data": {
    "items": [
      {
        "id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
        "name": "Acme Inc.",
        "website": "acme.com",
        "created_at": "2025-11-04T12:18:55.218Z"
      },
      {
        "id": "1be5a7d4-0c8b-4f1d-9b9c-12b9c0e5d2a4",
        "name": "Globex",
        "website": "globex.com",
        "created_at": "2026-01-22T09:02:11.503Z"
      }
    ],
    "total": 2,
    "page": 1,
    "size": 2,
    "total_pages": 1
  },
  "generated_at": "2026-06-08T14:30:11.218Z"
}

The response shape depends on the calling key:

Team-scoped key — data.items is a flat array of domains (id, name, website, created_at), all belonging to the key's single team. This is the original, unchanged format.
Master key — data.items is an array of teams, each { team_id, team_name, domains: [ … ] }, so a caller spanning multiple teams can attribute every domain to its owner.

To tell them apart in code: if an item has a domains array it's a team group (master key); otherwise items are domains directly (team key).

In both cases the per-user allowed_domains allowlist is applied, and teams without Developer Access are silently omitted. The endpoint is not paginated; total/page/size/total_pages count top-level items (domains for a team key, teams for a master key).

The 200 tab below shows the team key (flat) response. See Master key response for the grouped shape.

Master key response

A master key spans every team the caller belongs to, so data.items is an array of teams, each carrying its own domains array. Read the domain_id from items[].domains[], and use team_name to attribute a domain to its team.

{
  "data": {
    "items": [
      {
        "team_id": "b2c4e6a8-1f3d-4a5b-8c7e-9d0f1a2b3c4d",
        "team_name": "Acme Marketing",
        "domains": [
          {
            "id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
            "name": "Acme Inc.",
            "website": "acme.com",
            "created_at": "2025-11-04T12:18:55.218Z"
          }
        ]
      },
      {
        "team_id": "d4f6a8c0-3b5d-4e7f-9a1b-2c3d4e5f6a7b",
        "team_name": "Globex Growth",
        "domains": [
          {
            "id": "1be5a7d4-0c8b-4f1d-9b9c-12b9c0e5d2a4",
            "name": "Globex",
            "website": "globex.com",
            "created_at": "2026-01-22T09:02:11.503Z"
          }
        ]
      }
    ],
    "total": 2,
    "page": 1,
    "size": 2,
    "total_pages": 1
  },
  "generated_at": "2026-06-08T14:30:11.218Z"
}

Authorizations

header

Authorizationstring

Required

Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.

header

X-Request-Idstring

Optional UUID for log correlation. If omitted, we generate one and echo it back in the response.

Query parameters

This endpoint takes no query parameters.

Response

dataobject

Required

The list payload.

data.itemsarray

Required

For a team key, each item is a domain. For a master key, each item is a team group { team_id, team_name, domains }.

data.totalinteger

Required

Number of top-level items — domains for a team key, teams for a master key. Always equals items.length (endpoint isn't paginated).

data.pageinteger

Required

Current page (1-indexed). Always 1.

data.sizeinteger

Required

Items in this page. Equals items.length.

data.total_pagesinteger

Required

Total pages. Always 1.

generated_atstring

Required

ISO-8601 timestamp of when the server produced (or cached) this response.

Response headers

Header	Description
`X-Cache`	`HIT` or `MISS`. Indicates whether the response came from cache.
`X-Request-Id`	Unique request id. Echoes incoming if you set one.
`X-RateLimit-Limit`	Max requests per minute for this key.
`X-RateLimit-Remaining`	Requests remaining in current minute.
`X-RateLimit-Reset`	Unix epoch seconds when the window resets.

Caching

Cached for 1 hour per (user_id, key_team). Two users in the same team have separate cache entries because their allowed_domains may differ. Watch the X-Cache header to know whether you hit the cache.

Errors

401 Unauthorizederror

Missing, malformed, or revoked API key.

403 Forbiddenerror

Team's developer_access flag is off. Body matches the 403 example above.

429 Too Many Requestserror

Rate limit exceeded. Inspect the Retry-After header for how long to wait.

Empty result

If the caller has access to zero domains (allowlist excludes everything, team is empty, or all teams are filtered out), the response is a successful 200 with an empty list — items is [] for both key types:

{
  "data": { "items": [], "total": 0, "page": 1, "size": 0, "total_pages": 1 },
  "generated_at": "2026-06-08T14:30:11.218Z"
}

Was this page helpful?