Skip to content
Readsmith

Search API

POST/docs/_readsmith/api/search

Hybrid search over the site's indexed content: Postgres full-text fused with vector similarity when an embedding key is configured. No LLM is involved. `degraded: true` marks a response whose vector arm failed at request time, so the hits are keyword-only.

Search is the one endpoint most integrations start with, so it earns a page inside the guides as well as its row in the API tab. The generated contract below comes from this site's own OpenAPI spec; the console shows a working request against this very site.

Two behaviors worth knowing beyond the contract:

  • The degraded flag reports runtime health, not configuration. A site with a working embedding key still answers degraded: true when the provider is down or rate limited, so a client can label keyword-only results instead of silently serving worse ones.
  • Agents wanting full passages should use the MCP server's search_docs tool, which requests complete chunk text; the snippet field here is a display preview, never model grounding.
Request bodyapplication/jsonrequired
ScopedQuery
querystringrequiredminLen 1maxLen 2000

The search query or question.

versionstring

Docs version to scope to. Defaults to current.

localestring

Locale to scope to. Defaults to en.

Responses
200 OKRanked hits, possibly degraded to keyword-only.
SearchResult
hitsarrayrequired
items
SearchHit
idstringrequired

The chunk id.

kindstringrequired

Prose chunk or API operation.

Allowed values
docendpoint
titlestringrequired

The page or operation title.

snippetstringrequired

A short preview for display. Never model grounding.

textstring

The full chunk text, present only when the caller asked for it.

urlstringrequired

Deep link to the passage.

anchorstring | nullrequired

The heading anchor within the page.

headerPatharrayrequired

The heading trail above the passage.

items
string
methodstring | nullrequired

HTTP method, for endpoint hits.

pathstring | nullrequired

Operation path, for endpoint hits.

scorenumberrequired

Fused relevance score.

degradedbooleanrequired

True when the vector arm was expected but failed at request time: these hits are keyword-only.

400 Bad request
429 Too many requests
503 Unavailable
Request
▍POST/docs/_readsmith/api/search
cURL
curl 'https://readsmith.dev/docs/_readsmith/api/search' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{}'
POST/_readsmith/api/search
Request
Authorization
curl 'https://readsmith.dev/docs/_readsmith/api/search' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"query":"string"}'
Response
Send a request to see the response.
Response
200 OK
{
  "hits": [
    {
      "id": "string",
      "kind": "doc",
      "title": "string",
      "snippet": "string",
      "text": "string",
      "url": "string",
      "anchor": "string",
      "headerPath": [
        "string"
      ],
      "method": "string",
      "path": "string",
      "score": 0
    }
  ],
  "degraded": false
}
Was this page helpful?