Domains

List available trusted domains and categories for domain filtering.

GET https://api.persly.ai/v1/domains

Returns the public domain catalog used by domain filtering in Chat Completions and Finder.

Use this endpoint to discover domain values for include_domains and exclude_domains.

include_domains and exclude_domains are mutually exclusive on Chat/Finder requests. If both are provided in one request, the API returns 422.

Query Parameters

Parameter	Type	Required	Default	Description
`category`	string	No	—	Case-insensitive category filter (for example `guideline`, `policy`)
`q`	string	No	—	Case-insensitive substring search against normalized domain names
`limit`	integer	No	`200`	Maximum number of domains to return. Range: 1–1000.

Response Body

Field	Type	Description
`version`	string	Catalog schema version
`generated_at`	string	ISO 8601 timestamp when the catalog was generated
`total_domains`	integer	Number of domains returned after applying filters and limits
`domains`	array	Domain catalog entries
`domains[].domain`	string	Normalized domain (for example `nih.gov`)
`domains[].category`	string	Domain category. Returns `"unknown"` when no category metadata is available
`domains[].document_count`	integer	Number of indexed documents mapped to the domain
`domains[].in_trust_list`	boolean	Whether the domain is included in Persly's trust domain list
`categories`	array	Category-level summary for the returned domain set
`categories[].category`	string	Category name
`categories[].domain_count`	integer	Number of domains in the category
`categories[].document_count`	integer	Total indexed documents for domains in the category

Examples

List Domains

curl "https://api.persly.ai/v1/domains?limit=5"

import requests

response = requests.get(
    "https://api.persly.ai/v1/domains",
    params={"limit": 5},
)
data = response.json()

for item in data["domains"]:
    print(f"{item['domain']} ({item['category']}) - {item['document_count']} docs")

const response = await fetch("https://api.persly.ai/v1/domains?limit=5");
const data = await response.json();

for (const item of data.domains) {
  console.log(`${item.domain} (${item.category}) - ${item.document_count} docs`);
}

Response

{
  "version": "1.0",
  "generated_at": "2026-02-26T00:00:00Z",
  "total_domains": 2,
  "domains": [
    {
      "domain": "nih.gov",
      "category": "guideline",
      "document_count": 123,
      "in_trust_list": true
    },
    {
      "domain": "who.int",
      "category": "unknown",
      "document_count": 0,
      "in_trust_list": true
    }
  ],
  "categories": [
    {
      "category": "guideline",
      "domain_count": 1,
      "document_count": 123
    },
    {
      "category": "unknown",
      "domain_count": 1,
      "document_count": 0
    }
  ]
}

Filter by Category and Domain Query

curl "https://api.persly.ai/v1/domains?category=guideline&q=.gov&limit=20"

Errors

Status	Code	Cause
422	`—`	Invalid query parameter (for example, `limit > 1000`)
503	`service_unavailable`	Domain catalog metadata source temporarily unavailable