Skip to main content
GET
/
search
Search indexed content
curl --request GET \
  --url https://api.horizon.new/v1/search
{
  "results": [
    {
      "type": "document",
      "title": "<string>",
      "score": 123,
      "snippet": "<string>",
      "metadata": {}
    }
  ],
  "nextCursor": "<string>"
}
Query the Horizon index for contributed documents, generated artifacts, and workspace knowledge. The endpoint returns ranked results with embeddings-aware scoring so you can surface relevant material directly in your apps.

​
Query parameters

  • q — Required query string, up to 512 characters.
  • types — Optional comma-separated filters (document, artifact, contribution).
  • limit — Optional integer cap on results (1–50); defaults to 20.
  • cursor — Optional pagination token from a previous response.

​
Sample request

curl "https://api.horizon.new/v1/search?q=libraries&types=document,artifact&limit=5" \

​
Response

Returns 200 OK with a results array. Each result includes type, title, score, a short snippet, and any metadata provided at ingest time. Use nextCursor to continue paging if more hits are available.

​
Notes

  • Results omit archived contributions by default; include status=archived in the query string to surface them.
  • For semantic matches, keep queries conversational—single keywords bias toward exact tag matches.

​
x402 flow

Read-heavy search workloads are also metered through Coinbase’s x402 protocol. When usage exceeds your allowance, Horizon responds with a 402 challenge: 
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "20000",                // $0.02 in 6‑decimal USDC
      "resource": "GET /search",
      "description": "Horizon search query",
      "mimeType": "application/json",
      "payTo": "0xYourReceivingWallet",
      "maxTimeoutSeconds": 30,
      "asset": "0xYourUSDCContract",
      "extra": {
        "name": "USDC",
        "version": "1"
      }
    }
  ],
  "error": null
}
Process the challenge by:
  1. Supplying the accepts entry to a facilitator (/verify, /settle) as defined in the facilitator docs.
  2. Replaying the GET /search call with the facilitator-provided Base64 payload in the X-PAYMENT header: 
    curl "https://api.horizon.new/v1/search?q=libraries" \
  -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0="
  3. Horizon validates the payment and responds with the requested results. On success the response may include X-PAYMENT-RESPONSE for your accounting system.
Need help wiring the facilitator? Follow the Quickstart for sellers example project.

Query Parameters

​
q
string
required

Search query.

Maximum length: 512
​
types
string

Comma separated list of result types.

Example:

"document,asset"

​
limit
integer
default:20

Maximum number of results to return.

Required range: 1 <= x <= 50
​
cursor
string

Pagination cursor from the previous response.

Response

Search results returned

​
results
object[]
required
​
nextCursor
string | null
required