Skip to content

API reference

Search the web index

GET /v1/search

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.

Authentication
Send an API key or a service-account access token as a Bearer token.
Billing
Billing or an account spend limit can reject this request with 402.
Rate limits
A 429 response carries Retry-After; wait that long, then retry with backoff.

Parameters

  • query string query Required

    The search text.

    Minimum length
    • 1
    Maximum length
    • 512
  • limit integer query Optional

    The maximum number of results.

    Default
    • 20
    Minimum
    • 1
    Maximum
    • 50
  • lang string query Optional

    A two-letter lowercase language code that results must match.

    Pattern
    • ^[a-z]{2}$
  • ranking SearchRanking query Optional

    What the ranking favors. The default is balanced.

    Allowed
    • precision
    • balanced
    • authority
    • content_gap

Responses

  • 200

    Ranked projected search results

    SearchPostResponse X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-Request-ID
  • 400

    The query violated the public contract

    SearchV1Error X-Request-ID
  • 401

    A valid API key is required

    SearchV1Error X-Request-ID
  • 402

    Billing or a spend limit rejected execution

    SearchV1Error X-Request-ID
  • 403

    The API key lacks search permission

    SearchV1Error X-Request-ID
  • 429

    A rate limit rejected execution

    SearchV1Error Retry-AfterX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-Request-ID
  • 500

    The service could not safely complete the request

    SearchV1Error X-Request-ID
  • 502

    The search request could not be completed

    SearchV1Error X-Request-ID
  • 503

    Search is temporarily unavailable

    SearchV1Error X-Request-ID

SearchPostResponse

Public POST search response.

  • duration_ms integer Required

    The time taken to answer, in milliseconds.

    Minimum
    • 0
  • request_id string Required

    The reference of the request, to quote when contacting support.

  • results ProjectedPageResult[] Required

    The results, best first.

  • select SearchResultField[] Required

    The fields each result returns, after the default is applied.

Schemas

ErrorCode

Machine-readable product API failure.

Allowed values
  • 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
VariantType
1object
2object

PageResultFields

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

  • anchor null | string Optional

    Aggregated inbound anchor text.

  • author null | string Optional

    Page author.

  • categories null | object[] Optional

    Scored taxonomy categories.

  • content_angle null | string Optional

    Classified content angle.

  • description null | string Optional

    Result description.

  • document_intent null | string Optional

    Classified document intent.

  • domain null | string Optional

    Registrable or host domain.

  • domain_refdomains null | integer Optional

    Domain referring-domain count.

  • first_seen null | string Optional

    First-seen timestamp.

  • highlights null | string[] Optional

    Up to three query-relevant passages.

  • language null | string Optional

    Document language.

  • location null | string Optional

    Geographic location code.

  • page_type null | string Optional

    Page content type.

  • publish_time null | string Optional

    Published timestamp.

  • refdomains null | integer Optional

    Referring-domain count.

  • republished null | boolean Optional

    Whether the document was republished.

  • rule_type null | string Optional

    Applied rule type.

  • site_name null | string Optional

    Site display name.

  • title null | string Optional

    Page title.

  • url null | string Optional

    Canonical page URL.

  • word_count null | integer Optional

    Visible word count.

ProjectedPageResult

One ranked projected result.

  • fields PageResultFields Required

    Exactly the requested fields.

  • rank integer Required

    One-based result rank.

    Minimum
    • 1

SearchRanking

What the results should prioritize.

Allowed values
  • precision
  • balanced
  • authority
  • content_gap

SearchResultField

Public fields that may be selected in a search response.

Allowed values
  • url
  • title
  • description
  • anchor
  • site_name
  • author
  • language
  • domain
  • categories
  • location
  • page_type
  • publish_time
  • first_seen
  • refdomains
  • domain_refdomains
  • word_count
  • rule_type
  • document_intent
  • content_angle
  • republished
  • highlights

SearchV1Error

Search v1's original closed error envelope.

  • code ErrorCode Required

    Closed status category.

    Allowed
    • unauthenticated
    • forbidden
    • invalid_request
    • not_found
    • conflict
    • payment_required
    • too_many_requests
    • upstream
    • internal
  • message string Required

    Safe operator diagnostic.

  • reason SearchV1ErrorReason Required

    Closed Search v1 reason.

    Allowed
    • 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
  • recovery null | ErrorRecovery Optional
  • request_id string | null Optional

    The request reference, equal to the response's `X-Request-ID`; quote it to support.

  • validation null | ValidationReport Optional

SearchV1ErrorReason

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

Allowed values
  • 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.

  • allowed_values array | null Optional
    Maximum items
    • 16
  • code string Required

    Stable, extensible machine-readable category.

    Maximum length
    • 64
  • path string Required

    RFC 6901 pointer to the rejected location; empty means the root value.

    Maximum length
    • 1024
  • suggestion string Required

    Code-owned instruction for correcting the request.

    Maximum length
    • 512

ValidationReport

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

  • contract string Required

    Stable contract name, normally the published schema component name.

    Maximum length
    • 128
  • issues ValidationIssue[] Required

    At most eight deterministic violations. Correct every issue before retrying.

    Maximum items
    • 8
  • truncated boolean Required

    Whether more violations were omitted; retry after correcting the listed issues.

Use this request as an agent skill

Give your agent a reusable Yep Search API call.

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

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://platform.yep.com/api/v1/search' \
     --header "Authorization: Bearer $YEP_API_KEY" \
     --data-urlencode 'query=carbon border tax 2026' \
Request Open in workbench 
curl --get "https://platform.yep.com/api/v1/search" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --data-urlencode 'query=carbon border tax 2026'
Response 200 
{
  "duration_ms": 0,
  "request_id": "string",
  "results": [
    {
      "fields": {},
      "rank": 1
    }
  ],
  "select": [
    "url"
  ]
}

Commands

No matching commands

Confirm it's you