API reference

Search the web index

Returns ranked web results in the same envelope as `POST /api/v1/search`, projected to url, title, description, and language. The result cap is 50 and the API does not paginate.

GET /v1/search

Parameters

Request parameters

Name: query
In: query
Required: Yes
Type: string
Description: Non-empty search text.

Name: limit
In: query
Required: No
Type: integer
Description: Maximum returned results.

Name: lang
In: query
Required: No
Type: string
Description: Optional two-letter lowercase language code.

Name: coverage
In: query
Required: No
Type: SearchCoverage
Description: Search breadth; omission preserves balanced search.

Name: ranking
In: query
Required: No
Type: SearchRanking
Description: Ranking focus; omission preserves balanced search.

Request cURL

curl --get "https://yep.com/api/v1/search" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --data-urlencode 'query=carbon border tax 2026'

Use this request as an agent skill

Give your agent a reusable Yep Search API call.

Agent

Place the file at .agents/skills/yep-search/SKILL.md.

Download skill

SKILL.md preview markdown

---
name: yep-search
description: Search the web with the Yep Search API when a task needs current external sources or ranked web results.
---

# Search with Yep

Use the Yep Search API for requests that need web search results.

1. Read `YEP_API_KEY` from the environment. If it is missing, explain that it must be set and stop. Never ask the user to paste the key into chat, print it, or write it to source control.
2. Send the request with cURL, replacing the example query with the user's search terms:

   ```sh
   curl --get 'https://yep.com/api/v1/search' \
     --header "Authorization: Bearer $YEP_API_KEY" \
     --data-urlencode 'query=carbon border tax 2026' \

Responses

Response statuses

Status: 200
Description: Ranked projected search results
Body: SearchPostResponse

Status: 400
Description: The query 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: 500
Description: The service could not safely complete the request
Body: SearchV1Error

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

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

Schemas

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

PageResultFields

Optional nullable projected fields. Each property is omitted when not selected, `null` when selected but unavailable, or carries its typed value.

PageResultFields fields

Field: anchor
Required: No
Type: null | string
Description: Aggregated inbound anchor text.
Constraints

Field: author
Required: No
Type: null | string
Description: Page author.
Constraints

Field: categories
Required: No
Type: null | object[]
Description: Scored taxonomy categories.
Constraints

Field: content_angle
Required: No
Type: null | string
Description: Classified content angle.
Constraints

Field: description
Required: No
Type: null | string
Description: Result description.
Constraints

Field: document_intent
Required: No
Type: null | string
Description: Classified document intent.
Constraints

Field: domain
Required: No
Type: null | string
Description: Registrable or host domain.
Constraints

Field: domain_rating
Required: No
Type: null | number
Description: Domain rating.
Constraints

Field: domain_refdomains
Required: No
Type: null | integer
Description: Domain referring-domain count.
Constraints

Field: domain_traffic
Required: No
Type: null | integer
Description: Estimated domain traffic.
Constraints

Field: first_seen
Required: No
Type: null | string
Description: First-seen timestamp.
Constraints

Field: highlights
Required: No
Type: null | string[]
Description: Up to three query-relevant passages.
Constraints

Field: language
Required: No
Type: null | string
Description: Document language.
Constraints

Field: location
Required: No
Type: null | string
Description: Geographic location code.
Constraints

Field: page_type
Required: No
Type: null | string
Description: Page content type.
Constraints

Field: publish_time
Required: No
Type: null | string
Description: Published timestamp.
Constraints

Field: refclass_c
Required: No
Type: null | integer
Description: Refclass-C metric.
Constraints

Field: refdomains
Required: No
Type: null | integer
Description: Referring-domain count.
Constraints

Field: republished
Required: No
Type: null | boolean
Description: Whether the document was republished.
Constraints

Field: rule_type
Required: No
Type: null | string
Description: Applied rule type.
Constraints

Field: site_name
Required: No
Type: null | string
Description: Site display name.
Constraints

Field: title
Required: No
Type: null | string
Description: Page title.
Constraints

Field: traffic
Required: No
Type: null | integer
Description: Estimated URL traffic.
Constraints

Field: url
Required: No
Type: null | string
Description: Canonical page URL.
Constraints

Field: url_rating
Required: No
Type: null | number
Description: URL rating.
Constraints

Field: word_count
Required: No
Type: null | integer
Description: Visible word count.
Constraints

ProjectedPageResult

One ranked projected result.

ProjectedPageResult fields

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

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

SearchCoverage

How broad the search should be.

Request json

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

SearchPostResponse

Public POST search response.

SearchPostResponse 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: ProjectedPageResult[]
Description: Ranked projected results.
Constraints

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

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

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