Retrieval API

Search your own website's content from anywhere — a help desk, an internal tool, or an AI assistant you run. You get back the exact passages that answer a question, each with the page URL it came from. Nothing is generated and nothing is invented: if your site does not cover it, you get an empty list.

Your key

Create a key in the console under your domain, Connection keys. It is shown once. A key only ever reaches the single domain it was created for, and you can revoke it at any time.

Keep it server-side. Anyone holding it can read your site's indexed content.

Search

POST /api/public/v1/search

curl -s https://honeyvectors.com/api/public/v1/search \
  -H "Authorization: Bearer hvk_live_…" \
  -H "content-type: application/json" \
  -d '{"query":"do you ship to Canada?","limit":6}'

{
  "domain": "example.com",
  "query": "do you ship to Canada?",
  "count": 2,
  "results": [
    {
      "url": "https://example.com/shipping",
      "title": "Shipping",
      "heading": "Shipping > International",
      "text": "We ship to Canada in 3–5 working days…",
      "score": 0.812
    }
  ]
}

query is required, up to 500 characters. limit is optional, 1 to 20, and defaults to 6.

MCP server

The same content is available over the Model Context Protocol, so an AI client can use your website as a tool. Point your client at /api/public/mcp with the same key.

{
  "mcpServers": {
    "my-site": {
      "url": "https://honeyvectors.com/api/public/mcp",
      "headers": { "Authorization": "Bearer hvk_live_…" }
    }
  }
}

Two tools are exposed: search_site (query, limit) and site_summary, which returns the machine-readable briefing built from your pages.

Errors and limits

Every failure returns the same shape, so you can branch on the code rather than the wording.

{ "error": { "code": "rate_limited", "message": "This key is limited to 60 requests a minute." } }

unauthorized — missing, malformed, unknown or revoked key (401)
rate_limited — per-key ceiling, retry after the header says (429)
allowance_exhausted — the account's monthly allowance is used (429)
plan_required — the API is not included in this plan (403)
missing_query, query_too_long, invalid_limit, invalid_body (400)
unavailable — search is briefly down; retry (503)

Good to know

Results reflect your last read of the site. Re-read after a big content change.
Scores run 0 to 1. Anything below the relevance floor is dropped rather than returned weakly.
A key cannot be pointed at another domain — the domain is fixed when the key is made.
Requests are logged for your own view in the console: endpoint, status and result count only.

Questions? Open the console.