Finkkle API Overview: Authentication and Integration Patterns

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

The Finkkle API gives you programmatic access to search results, the Spaces AI stream, vertical content, and utility data. All endpoints are served over HTTPS and authenticated with Bearer tokens. This page covers authentication, rate limits, and integration patterns that apply to every endpoint.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer <your-api-key>

Get an API key

Sign in at one.finkkle.com
Click Create API key in the dashboard
Give your key a name that identifies its scope (e.g., prod-search, dev-test)
Copy the key immediately — it is displayed only once

Store API keys on the server side only. Never include them in client-side JavaScript, mobile app source code, or public repositories. Rotate keys immediately when a team member’s access changes or if a key is exposed.

Key scopes

Keys are scoped to the routes they are allowed to call. Use separate keys for different environments and different integrations — a key used in production should not be the same key used in development.

Rate limits

Route type	Limit
Foundation routes (search, suggestions)	20 requests / minute per IP

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff for retries:

async function searchWithRetry(query, attempt = 0) {
  const res = await fetch(`https://api.finkkle.com/api/v1/search?q=${encodeURIComponent(query)}`, {
    headers: { Authorization: `Bearer ${process.env.FINKKLE_API_KEY}` },
  });
  if (res.status === 429 && attempt < 4) {
    await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 500));
    return searchWithRetry(query, attempt + 1);
  }
  return res.json();
}

Integration pattern

Authenticate at your backend

Store your API key in an environment variable. Never send it to the client.

export FINKKLE_API_KEY=your_key_here

Validate and normalize inputs

Validate query inputs before sending them to the API. Ensure q is non-empty and meets the minimum length requirement.

Call with an explicit timeout

Set a timeout on every API call — network conditions vary and upstream services can be slow:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);
const res = await fetch(url, { signal: controller.signal });
clearTimeout(timeout);

Log request IDs

Capture request IDs from response headers for debugging and support escalation. Pass them when contacting support.

Webhooks and event handling

For streaming endpoints and event-driven integrations:

Handle events idempotently — store the event ID before applying side effects
Acknowledge quickly — return a 200 response immediately, process the payload asynchronously
Retry with backoff — use exponential backoff for transient failures (network errors, 5xx responses)
Do not retry 4xx errors — these indicate a problem with your request that retrying will not fix

Available endpoints

Endpoint	Description
`GET /api/v1/search`	Versioned search — recommended for new integrations
`GET /api/search`	Legacy static search
`GET /api/search/stream`	Streaming search via SSE
`POST /api/spaces/stream`	Spaces AI conversation stream
`GET /api/images`	Image vertical
`GET /api/videos`	Video vertical
`GET /api/shopping`	Shopping vertical
`GET /api/utility-card`	Utility cards (calculator, weather, etc.)
`GET /api/suggestions`	Autocomplete suggestions
`GET /api/stats`	Usage and index statistics
`GET /v1/health`	Health check

See individual endpoint pages for full parameter and response documentation.

Platform

API Reference

Account & Plans

Finkkle API Overview: Authentication and Integration Patterns

Authentication

Get an API key

Key scopes

Rate limits

Integration pattern

Webhooks and event handling

Available endpoints

​Authentication

​Get an API key

​Key scopes

​Rate limits

​Integration pattern

​Webhooks and event handling

​Available endpoints

Authentication

Get an API key

Key scopes

Rate limits

Integration pattern

Webhooks and event handling

Available endpoints