The site’s search, addressed by a machine.

A search service with visible limits.

Call this deployment’s enriched search and domain assessments with scoped keys, measured units, and hard caps.

request → reserve → response

What crosses the wire.

POST/api/v1/search

date_from / date_toYYYY-MM-DD | null
min_authority_scorenumber 0–100 | null
site_naturesenum[]
languagesBCP47 short[]
countriesISO alpha-2[]
include_domains / exclude_domainshostname[]
lens_iduuid | null

Idempotency-Key: {idempotency_key}

usage · unit · committed

Response envelope

copy

{
  "data": {
    "search_id": uuid,
    "organic_results": [{
      "organic_position": integer,
      "title": string, "snippet": string,
      "destination_url": string,
      "domain": { "hostname": string,
        "authority_score": number | null,
        "measured_at": date | null },
      "published_date": date | null,
      "retrieval_source": "owned_lexical" | "owned_semantic"
        | "owned_hybrid" | "external_gap" }],
    "ads": [sponsored_item],
    "answer": { "state": "supported" | "abstained"
      | "failed" | "disabled", "claims": [] },
    "coverage": { … }, "pagination": { … }
  },
  "usage": { "units_reserved": integer,
    "units_committed": integer,
    "period_remaining": integer },
  "request_id": uuid
}

statemethodpathtime

committedPOST/api/v1/search
releasedGET/api/v1/domains/{domain}
committedPOST/api/v1/usage/estimate

authentication

A scoped key, never recovered.

Bearer authentication identifies the caller; scopes decide what that key may read.

scheme: bearer
storage: hashed at rest
recovery: unavailable after creation
scopes: search · domains · usage
last use: recorded

Authorization: Bearer {your_key}

key management · /settings/api-keys

metering

A unit has one meaning.

Automatic overage is disabled.

accepted search
One enriched-search request commits one unit.
idempotent retry
The same key does not charge twice.
hard cap
The request is refused; no overage is charged.

not measured

parameters

The site and service share a filter contract.

Every class combines with the others; none widens the configured vertical.

The typed filter contract
field	type
date_from / date_to optional	YYYY-MM-DD \| null
min_authority_score optional	number 0–100 \| null
site_natures optional	enum[]
languages optional	BCP47 short[]
countries optional	ISO alpha-2[]
include_domains / exclude_domains optional	hostname[]
lens_id optional	uuid \| null

news
personal_blog
forum
store
institutional
aggregator
content_farm
reference
other

A filter that reaches outside the owner’s published vertical is refused, and the refusal names the field and the values it rejected. It is never dropped in silence: a silent drop would tell you your scope applied when it did not.

declared outcomes

Failure is part of the contract.

answer.abstained
The results array remains; the answer says the retrieved evidence does not support an answer.
provider_failure
An external provider failed and no admitted fallback exists. Owned results return with narrower coverage declared.
unconfigured
A slot this instance has never configured. The response names the cause; nothing is fabricated and nothing reads as zero.
allowance_exhausted
The reservation is released; nothing is committed and no charge follows.