> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkkle.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Complete reference for the Finkkle Search API — versioned GET /api/v1/search, streaming SSE search, and vertical endpoints for images, video, and shopping.

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

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

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

### Parameters

<ParamField query="q" type="string" required>
  The search query. Also accepted as `query`. Minimum 2 characters.
</ParamField>

<ParamField query="limit" type="number">
  Number of results to return. Accepted range: 1–10. Defaults to 10.
</ParamField>

<ParamField query="safe_search" type="boolean">
  Filter explicit content. Defaults to `true`.
</ParamField>

<ParamField query="domains" type="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.
</ParamField>

<ParamField query="personalization" type="boolean">
  Apply user interest weights to ranking. Defaults to `true` when authenticated. Set to `false` for consistent, reproducible results in multi-user integrations.
</ParamField>

### Response

```json theme={null}
{
  "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

<ResponseField name="version" type="string">
  API version string.
</ResponseField>

<ResponseField name="results" type="array">
  Ranked list of search results.

  <Expandable title="Result object fields" />
</ResponseField>

<ResponseField name="rateLimit" type="object">
  Current rate limit status for your key.
</ResponseField>

## GET /api/search (Legacy static search)

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

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

<ParamField query="q" type="string" required>
  The query string.
</ParamField>

<ParamField query="offset" type="number">
  Result offset for pagination. Defaults to 0.
</ParamField>

<ParamField query="safeSearch" type="boolean">
  Restrict explicit results. Defaults to `true`.
</ParamField>

<ParamField query="personalization" type="boolean">
  Apply topic interest weights. Defaults to `true`.
</ParamField>

## GET /api/search/stream (SSE)

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

```bash theme={null}
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                                           |

```javascript theme={null}
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](/one/error-codes) for the full reference including system-level errors.