> ## 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 API Overview: Authentication and Integration Patterns

> Get started with the Finkkle API — generate an API key, authenticate requests with Bearer tokens, understand rate limits, and follow integration best practices.

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

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:

```bash theme={null}
Authorization: Bearer <your-api-key>
```

### Get an API key

1. Sign in at [one.finkkle.com](https://one.finkkle.com)
2. Click **Create API key** in the dashboard
3. Give your key a name that identifies its scope (e.g., `prod-search`, `dev-test`)
4. Copy the key immediately — it is displayed only once

<Warning>
  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.
</Warning>

### 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:

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

<Steps>
  <Step title="Authenticate at your backend">
    Store your API key in an environment variable. Never send it to the client.

    ```bash theme={null}
    export FINKKLE_API_KEY=your_key_here
    ```
  </Step>

  <Step title="Validate and normalize inputs">
    Validate query inputs before sending them to the API. Ensure `q` is non-empty and meets the minimum length requirement.
  </Step>

  <Step title="Call with an explicit timeout">
    Set a timeout on every API call — network conditions vary and upstream services can be slow:

    ```javascript theme={null}
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 10000);
    const res = await fetch(url, { signal: controller.signal });
    clearTimeout(timeout);
    ```
  </Step>

  <Step title="Log request IDs">
    Capture request IDs from response headers for debugging and support escalation. Pass them when contacting support.
  </Step>
</Steps>

## 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.