API reference

Find domains with typed filters and result projection

Returns ranked domains using the same filter and projection language as page search.

POST /v1/search/domains

Request body

JSON body: DomainSearchPostRequest

Request cURL

curl --request POST "https://yep.com/api/v1/search/domains" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "query": "independent climate policy research",
  "limit": 10,
  "select": [
    "domain",
    "domain_traffic"
  ],
  "filter": "@domain_traffic >= 1000"
}
JSON

Responses

Response statuses

Status: 200
Description: Ranked projected domain results
Body: DomainSearchPostResponse

Status: 400
Description: The request violated the public contract
Body: SearchV1Error

Status: 401
Description: A valid API key is required
Body: SearchV1Error

Status: 402
Description: Billing or a spend limit rejected execution
Body: SearchV1Error

Status: 403
Description: The API key lacks search permission
Body: SearchV1Error

Status: 429
Description: A rate limit rejected execution
Body: SearchV1Error

Status: 502
Description: The search request could not be completed
Body: SearchV1Error

Status: 503
Description: Search is temporarily unavailable
Body: SearchV1Error

Schemas

DomainResultFields

Typed fields returned by domain search. Properties are omitted when not selected.

DomainResultFields fields

Field: domain
Required: No
Type: string
Description: Registrable domain.
Constraints

Field: domain_traffic
Required: No
Type: null | ProjectedValue_u64
Description
Constraints

DomainSearchPostRequest

Public domain-search request. It deliberately reuses the page search filter and projection vocabularies; the domain view limits both to `domain` and `domain_traffic`.

DomainSearchPostRequest fields

Field: filter
Required: No
Type: string | null
Description: Optional eligibility filter in the public filter language.
Constraints: min length: 1; max length: 65536

Field: limit
Required: No
Type: integer | null
Description: Maximum result count; defaults to 20 and is capped at 100.
Constraints: min: 1; max: 100

Field: query
Required: Yes
Type: string
Description: Non-empty search text.
Constraints: min length: 1; max length: 512

Field: select
Required: Yes
Type: SearchResultField[]
Description: Required non-empty response projection.
Constraints: min items: 1

DomainSearchPostResponse

Public domain-search response.

DomainSearchPostResponse fields

Field: duration_ms
Required: Yes
Type: integer
Description: End-to-end duration in milliseconds.
Constraints: min: 0

Field: request_id
Required: Yes
Type: string
Description: Public request correlation identifier.
Constraints

Field: results
Required: Yes
Type: ProjectedDomainResult[]
Description: Ranked projected domains.
Constraints

Field: select
Required: Yes
Type: SearchResultField[]
Description: Echoed normalized projection.
Constraints

ErrorCode

Machine-readable product API failure.

Request json

[
  "unauthenticated",
  "forbidden",
  "invalid_request",
  "not_found",
  "conflict",
  "payment_required",
  "too_many_requests",
  "upstream",
  "internal"
]

ErrorRecovery

Browser-safe recovery action selected by the authoritative product boundary.

ErrorRecovery alternatives

Variant: 1
Type: object

Variant: 2
Type: object

Variant: 3
Type: object

ProjectedDomainResult

One ranked projected domain result.

ProjectedDomainResult fields

Field: fields
Required: Yes
Type: DomainResultFields
Description: Exactly the requested fields.
Constraints

Field: rank
Required: Yes
Type: integer
Description: One-based result rank.
Constraints: min: 1

ProjectedValue_u64

ProjectedValue_u64 alternatives

Variant: 1
Type: null

Variant: 2
Type: integer

SearchResultField

Public fields that may be selected in a search response.

Request json

[
  "url",
  "title",
  "description",
  "anchor",
  "site_name",
  "author",
  "language",
  "domain",
  "categories",
  "location",
  "page_type",
  "publish_time",
  "first_seen",
  "url_rating",
  "domain_rating",
  "traffic",
  "refdomains",
  "domain_traffic",
  "domain_refdomains",
  "refclass_c",
  "word_count",
  "rule_type",
  "document_intent",
  "content_angle",
  "republished",
  "highlights"
]

SearchV1Error

Search v1's original closed error envelope.

SearchV1Error fields

Field: agent_session_id
Required: No
Type: string | null
Description: Always absent for search; retained because runtime errors use one envelope.
Constraints

Field: code
Required: Yes
Type: ErrorCode
Description: Closed status category.
Constraints

Field: message
Required: Yes
Type: string
Description: Safe operator diagnostic.
Constraints

Field: reason
Required: Yes
Type: SearchV1ErrorReason
Description: Closed Search v1 reason.
Constraints

Field: recovery
Required: No
Type: null | ErrorRecovery
Description
Constraints

Field: validation
Required: No
Type: null | ValidationReport
Description
Constraints

SearchV1ErrorReason

Closed failure-reason vocabulary retained for the published Search v1 contract.

Request json

[
  "malformed_request",
  "authentication_required",
  "permission_denied",
  "api_key_name_invalid",
  "spend_policy_invalid",
  "rate_policy_invalid",
  "resource_not_found",
  "state_conflict",
  "insufficient_funds",
  "spend_limit_exceeded",
  "rate_limit_exceeded",
  "dependency_unavailable",
  "internal_failure"
]

ValidationIssue

One actionable, privacy-safe contract violation.

ValidationIssue fields

Field: allowed_values
Required: No
Type: array | null
Description
Constraints: max items: 16

Field: code
Required: Yes
Type: string
Description: Stable, extensible machine-readable category.
Constraints: max length: 64

Field: path
Required: Yes
Type: string
Description: RFC 6901 pointer to the rejected location; empty means the root value.
Constraints: max length: 1024

Field: suggestion
Required: Yes
Type: string
Description: Code-owned instruction for correcting the request.
Constraints: max length: 512

ValidationReport

Bounded validation feedback shared by model, REST, and MCP boundaries.

ValidationReport fields

Field: contract
Required: Yes
Type: string
Description: Stable contract name, normally the published schema component name.
Constraints: max length: 128

Field: issues
Required: Yes
Type: ValidationIssue[]
Description: At most eight deterministic violations. Correct every issue before retrying.
Constraints: max items: 8

Field: truncated
Required: Yes
Type: boolean
Description: Whether more violations were omitted; retry after correcting the listed issues.
Constraints