Domains

List available trusted domains and categories for domain filtering.

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

Returns a public trust-domain catalog you can use to choose common include_domains and exclude_domains values for Chat Completions and Finder. Requests are not validated against this catalog at runtime.

Use this endpoint to narrow down filter values before sending Chat/Finder requests.

This is a public endpoint. API key authentication is not required.

include_domains and exclude_domains are mutually exclusive on Chat/Finder requests. Sending both as non-empty arrays returns 422.

The catalog is served from a cached snapshot. generated_at is the snapshot generation time. On transient source refresh failures, the API may return the last-good snapshot; if no usable snapshot exists, the endpoint returns 503 service_unavailable.

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.

Category values are data-dependent. Query without filters first, then pick values from the categories array. Filtered requests can validly return an empty list.

Results are sorted by document_count (descending) and then domain (ascending). The categories summary is calculated from the returned domains array after category, q, and limit are applied. Domains excluded by limit are not counted.

Response Body

Field	Type	Description
`version`	string	Catalog schema version
`generated_at`	string	ISO 8601 snapshot generation timestamp (can represent a last-good cached snapshot)
`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	Always `true` in this endpoint because only trust-list domains are returned
`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-01-01T00: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