Search developer documentation API

Endpoint facts

Method

POST

API path

/developer/search

Auth

jwt or apiKey

Credits

3 credits/request

Charged on

Successful 2xx responses only

Platform

Retrieval

Execution

Managed browser rendering where the target needs it

Response schema

#/definitions/developerretrieval.developerSearchResponseDoc

Request body schema

#/definitions/developerretrieval.DeveloperSearchRequest

How this endpoint behaves

Searches indexed documents only. It never fetches a source or starts ingestion. The current ready source is go:docs, covering only the selected 18 verified pages returned by /developer/sources.

Request body

• q: required on the first page; 1–2,000 characters. Unicode-aware lexical matching preserves punctuation identifiers such as context.Context, io.EOF, and -flag. When other content terms remain, a small set of ordinary question words is ignored for ranking. Literal queries consisting only of those words remain searchable; stored index terms and frozen continuation order are unchanged.
• sources: optional, at most 20 unique source IDs. The only currently registered ID is go:docs.
• types: optional unique values from doc, readme, issue, and pull_request. The current source supports only doc; the other documented enum values are rejected for this source.
• version: optional string, but unsupported by the current unversioned Go documentation source and rejected with 400.
• limit: optional integer from 1–50; defaults to 10.
• passages_per_result: optional integer from 1–5; defaults to 2.
• cursor: optional opaque cursor. When present, the body may contain only cursor and optional limit.

Scalar values must appear once. Unknown JSON fields are rejected. Search pages are frozen, owner-scoped snapshots; a continuation reads the frozen result payload and does not search a newer index. Public response data is kept below 960 KiB; if needed, a continuation returns a smaller page with its cursor advanced only through the last returned item.

Response behavior

• items contains id, source_id, type, canonical url, revision, indexed_at, exact matched passages, and rank. Passage locators point into the retained normalized document bytes.
• coverage.status values are ok, failed, not_indexed, and unsupported.
• warnings.code values are source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, and cached_source_stale.
• partial is true when a source is not indexed or the bounded 200-document ranking window is exhausted.
• A first-page logical search reports usage.search_requests=1. Cursor-only continuation reports zero usage. credits_charged and settlement_pending reflect the actual billing receipt.

Example request:

{
  "q": "Go assembler",
  "sources": ["go:docs"],
  "types": ["doc"],
  "limit": 10,
  "passages_per_result": 2
}

Shared response schema enum values (the owning endpoint emits its own job kind): blocked, budget_exhausted, duplicate, full_text_unavailable, idempotency_conflict, internal_error, invalid_cursor, invalid_url, limit_reached, not_found, out_of_scope, rate_limited, result_expired, robots_disallowed, timeout, unknown_source, unsupported_content_type, unsupported_filter, upstream_error.

Shared guides

Related