API reference

Build a typed search request from natural language

Uses the selected allowlisted model and stored BYOK provider key. A successful validated build is billed as one Agent API run and does not execute search.

POST /v1/query-builder

Request body

JSON body: QueryBuilderRequest

Request cURL

curl --request POST "https://yep.com/api/v1/query-builder" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "instruction": "Find independent climate policy research with meaningful traffic.",
  "model": {
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4.5"
  }
}
JSON

Responses

Response statuses

Status: 200
Description: Validated public search request.
Body: QueryBuilderResponse

Status: 400
Description: Invalid request.
Body: PublicApiError

Status: 401
Description: Authentication required.
Body: PublicApiError

Status: 402
Description: Agent API funds or a spend limit rejected execution.
Body: PublicApiError

Status: 403
Description: The API key lacks agent permission.
Body: PublicApiError

Status: 409
Description: No stored provider key can run the selected model; recovery includes the setup URL.
Body: PublicApiError

Status: 429
Description: The request exceeded a rate boundary.
Body: PublicApiError

Status: 500
Description: The service could not safely complete the operation.
Body: PublicApiError

Status: 502
Description: The model returned an invalid request.
Body: PublicApiError

Status: 503
Description: Inference is temporarily unavailable.
Body: PublicApiError

Schemas

AgentModelRef

One allowlisted inference provider and model identifier.

AgentModelRef fields

Field: model
Required: Yes
Type: string
Description: Provider-native model identifier.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Closed provider discriminator.
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

ProviderKeyProvider

Closed provider set exposed to product clients.

Request json

[
  "openrouter"
]

PublicApiError

Stable public error envelope for APIs whose reason vocabulary is extensible.

PublicApiError fields

Field: agent_session_id
Required: No
Type: string | null
Description: Agent execution correlation id, present after an invocation is admitted.
Constraints

Field: code
Required: Yes
Type: ErrorCode
Description: Closed status category suitable for program control flow.
Constraints

Field: message
Required: Yes
Type: string
Description: Safe diagnostic intended for operators, not program branching.
Constraints

Field: reason
Required: Yes
Type: string
Description: Extensible machine-readable detail; clients must accept unknown values.
Constraints

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

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

QueryBuilderRequest

Public natural-language query-builder request.

QueryBuilderRequest fields

Field: current_request
Required: No
Type: null | SearchPostRequest
Description
Constraints

Field: instruction
Required: Yes
Type: string
Description: Natural-language search goal.
Constraints: min length: 1; max length: 4096

Field: model
Required: Yes
Type: AgentModelRef
Description: Exact allowlisted BYOK model.
Constraints

QueryBuilderResponse

Public validated query-builder response.

QueryBuilderResponse fields

Field: canonical_filter
Required: No
Type: string | null
Description: Canonical text form of `request.filter`, when present.
Constraints

Field: request
Required: Yes
Type: SearchPostRequest
Description: Complete public search request.
Constraints

Field: request_id
Required: Yes
Type: string
Description: Billing and support correlation identifier.
Constraints

SearchCoverage

How broad the search should be.

Request json

[
  "balanced",
  "high",
  "maximum"
]

SearchPostRequest

Public POST search request.

SearchPostRequest fields

Field: coverage
Required: No
Type: null | SearchCoverage
Description
Constraints

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

Field: lang
Required: No
Type: string | null
Description: Optional two-letter lowercase language code.
Constraints: pattern: ^[a-z]{2}$

Field: limit
Required: No
Type: integer | null
Description: Maximum result count; defaults to 20 at the product boundary.
Constraints: min: 1; max: 50

Field: max_results_per_domain
Required: No
Type: integer | null
Description: Optional maximum number of results from one registrable domain.
Constraints: min: 1; max: 10

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

Field: ranking
Required: No
Type: null | SearchRanking
Description
Constraints

Field: select
Required: No
Type: SearchResultField[]
Description: Response projection; omission selects the stable summary fields.
Constraints: min items: 1

SearchRanking

What the results should prioritize.

Request json

[
  "precision",
  "balanced",
  "authority",
  "content_gap"
]

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"
]

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

Query builder