Finkkle / API Reference

API Reference

Finkkle API Services

Access search results, streaming AI, collaborative discovery, suggestions, and vertical feeds programmatically.

Reference manual · Finkkle documentation

Core Search APIs

The Fastify backend serves search content via two primary routes: static JSON endpoints and Server-Sent Events (SSE) streaming paths.

Static Search

GET /api/search

Returns a complete payload containing lexical matches, suggestions, and vertical cards in a single response.

  • q (string, required): The query string to look up.
  • offset (number, optional): Result offset for pagination. Defaults to 0.
  • safeSearch (boolean, optional): Restricts explicit results if set to true.
  • personalization (boolean, optional): Applies topic interest weights if enabled.

Streaming Search (SSE)

GET /api/search/stream

Preferred by the desktop and mobile SERP clients for near-zero perceived latency. Streams search results and enrichments incrementally.

Listeners should expect the following SSE event sequence:

  1. ack: Confirms connection initialization.
  2. fast_init: Streams critical early UI structures.
  3. result_batch: Incremental blocks of search result rows.
  4. enrichment: Asynchronous details such as Wikipedia knowledge panels, calculators, weather, or shopping cards.
  5. done: Connection closure notification.

Finkkle Spaces Streams

POST /api/spaces/stream

Powers the collaborative discovery space. Orchestrated by a Groq planning assistant model, it accepts conversation history and returns a synthesized streaming text response, executing tools behind the scenes.

POST /api/spaces/stream
Content-Type: application/json

{
  "history": [
    {"role": "user", "content": "Find the latest prices for iPhone 15 Pro"}
  ]
}

Vertical & Enrichment APIs

Finkkle provides dedicated APIs for specific media type lookups and utility processing:

  • GET /api/images: Dedicated image search queries, matching tags and embeddings.
  • GET /api/videos: Dedicated video search results (e.g. YouTube and local files).
  • GET /api/shopping: Direct access to seeded product arrays with filtering rules (min/max price auto-swapping).
  • GET /api/utility-card: Resolves structural query cards (e.g. calculator, translation, dictionary, timer).
  • GET /api/suggestions: Prefix matching for autocomplete search bar suggestions.

Authentication & Headers

When the environment has authentication active (AUTH_ENABLED=true), API routes require valid session indicators in the headers:

Authorization: Bearer <supabase-anon-token>

These tokens are validated against the configured Supabase client region. Stale or invalid headers will trigger ERR_AUTH_FAILED errors.