Finkkle Search API Reference: GET /api/v1/search

Finkkle One is currently undergoing a major overhaul. The Search API is disabled until further notice. Finkkle Trends remains accessible. More details soon.

The Finkkle Search API provides programmatic access to the same results you see on finkkle.com. Use the versioned GET /api/v1/search endpoint for new integrations. For lower latency in user-facing products, use the SSE streaming endpoint.

GET /api/v1/search

The recommended endpoint for new integrations. Returns an external-safe JSON response with ranked results and metadata.

Request

GET https://api.finkkle.com/api/v1/search?q=privacy+browser&limit=5&domains=mozilla.org
Authorization: Bearer <your-api-key>

Parameters

string

required

The search query. Also accepted as query. Minimum 2 characters.

number

Number of results to return. Accepted range: 1–10. Defaults to 10.

boolean

Filter explicit content. Defaults to true.

string

Comma-separated list of domains to restrict results to (e.g., mozilla.org,mdn.org). Filters returned URLs by host — does not trigger crawling.

boolean

Apply user interest weights to ranking. Defaults to true when authenticated. Set to false for consistent, reproducible results in multi-user integrations.

Response

{
  "version": "1",
  "schemaVersion": "gamma-3.7",
  "query": "privacy browser",
  "results": [
    {
      "rank": 1,
      "title": "Firefox: Privacy-focused web browser",
      "url": "https://www.mozilla.org/firefox",
      "displayUrl": "mozilla.org/firefox",
      "snippet": "Firefox is a fast, private browser from Mozilla...",
      "source": "web",
      "score": 0.94
    }
  ],
  "meta": {
    "totalResults": 42,
    "processingTimeMs": 87
  },
  "rateLimit": {
    "limit": 20,
    "remaining": 19,
    "resetAt": "2024-01-15T10:01:00Z"
  }
}

Response fields

string

API version string.

array

Ranked list of search results.

Show Result object fields

object

Current rate limit status for your key.

GET /api/search (Legacy static search)

The original search endpoint. Returns a complete payload with lexical matches, suggestions, and vertical cards.

GET https://api.finkkle.com/api/search?q=best+laptops+2024&offset=0&safeSearch=true
Authorization: Bearer <your-api-key>

string

required

The query string.

number

Result offset for pagination. Defaults to 0.

boolean

Restrict explicit results. Defaults to true.

boolean

Apply topic interest weights. Defaults to true.

GET /api/search/stream (SSE)

Preferred for user-facing products. Streams results incrementally for near-zero perceived latency.

GET https://api.finkkle.com/api/search/stream?q=electric+vehicles
Authorization: Bearer <your-api-key>

The SSE connection emits a sequence of events:

Event	Description
`ack`	Connection initialized
`fast_init`	Early UI structures streamed immediately
`result_batch`	Incremental blocks of search result rows
`enrichment`	Asynchronous details — knowledge panels, calculators, weather, shopping cards
`done`	Stream complete, connection closing

const es = new EventSource(
  `https://api.finkkle.com/api/search/stream?q=${encodeURIComponent(query)}`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
);

es.addEventListener('result_batch', (e) => {
  const batch = JSON.parse(e.data);
  renderResults(batch.results);
});

es.addEventListener('done', () => es.close());

Vertical endpoints

Endpoint	Query params	Returns
`GET /api/images`	`q` (required)	Image results with tags and source URLs
`GET /api/videos`	`q` (required)	Video results from indexed sources
`GET /api/shopping`	`q`, `minPrice`, `maxPrice`	Product cards with prices and merchant links
`GET /api/utility-card`	`q`	Utility cards — calculator, translator, weather, currency, timer
`GET /api/suggestions`	`q`	Autocomplete prefix-match array
`GET /api/stats`	—	Usage and index statistics for your API key

All vertical endpoints use the same Authorization: Bearer header.

Error codes

Code	Meaning
`missing_query`	No `q` or `query` parameter provided
`query_too_short`	Query is below the minimum length
`missing_api_key`	No `Authorization` header present
`invalid_api_key`	Key is malformed or not recognized
`search_failed`	Upstream search error — retry with backoff

See Error Codes for the full reference including system-level errors.

Platform

API Reference

Account & Plans

Finkkle Search API Reference: GET /api/v1/search

GET /api/v1/search

Request

Parameters

Response

Response fields

GET /api/search (Legacy static search)

GET /api/search/stream (SSE)

Vertical endpoints

Error codes

​GET /api/v1/search

​Request

​Parameters

​Response

​Response fields

​GET /api/search (Legacy static search)

​GET /api/search/stream (SSE)

​Vertical endpoints

​Error codes

GET /api/v1/search

Request

Parameters

Response

Response fields

GET /api/search (Legacy static search)

GET /api/search/stream (SSE)

Vertical endpoints

Error codes