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

# Doofinder API Reference

> Complete reference for the Doofinder suite of APIs. Build powerful search experiences, manage your data, and unlock analytics insights.

# References

Doofinder provides a suite of APIs to power search, personalization, and analytics for your ecommerce site.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/introduction/quickstart">
    Get your first API call running in under 5 minutes.
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/search-api/overview">
    Query indexed items, get autocomplete suggestions, run image search, and log user interactions in real time.
  </Card>

  <Card title="Management API" icon="gears" href="/management-api/overview">
    Create and configure search engines, manage indices, and push or update items programmatically.
  </Card>

  <Card title="Stats API" icon="chart-bar" href="/stats-api/overview">
    Retrieve analytics — sessions, top searches, click-through rates, conversion data, and more.
  </Card>

  <Card title="Recommendations API" icon="stars" href="/recommendations-api/overview">
    Deliver personalized product recommendations powered by Doofinder's recommendation engine.
  </Card>

  <Card title="Category Merchandising API" icon="layer-group" href="/category-merchandising/overview">
    Configure and manage category-level search rules and boost strategies.
  </Card>
</CardGroup>

## Architecture Overview

All Doofinder APIs are region-scoped. Your **search zone** determines the hostname to use:

| Zone  | Region        | Base domain           |
| ----- | ------------- | --------------------- |
| `eu1` | Europe        | `eu1-*.doofinder.com` |
| `us1` | United States | `us1-*.doofinder.com` |
| `ap1` | Asia Pacific  | `ap1-*.doofinder.com` |

Each API uses a different subdomain pattern:

| API                    | Base URL                                              |
| ---------------------- | ----------------------------------------------------- |
| Search API             | `https://{zone}-search.doofinder.com`                 |
| Management API         | `https://{zone}-api.doofinder.com`                    |
| Stats API              | `https://{zone}-api.doofinder.com`                    |
| Recommendations API    | `https://{zone}-recommendations.doofinder.com`        |
| Category Merchandising | `https://{zone}-category-merchandising.doofinder.com` |

<Note>
  Your search zone is shown in the [Doofinder Admin Panel](https://admin.doofinder.com). The zone prefix on API keys (e.g. `eu1-ab46030x...`) is optional — the zone is determined by the hostname you call.
</Note>

## Authentication at a Glance

All APIs authenticate via an `Authorization` HTTP header. The format depends on the API:

<CodeGroup>
  ```bash Search API theme={null}
  curl "https://eu1-search.doofinder.com/6/{hashid}/_search?query=shoes" \
    -H "Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07"
  ```

  ```bash Management & Stats API theme={null}
  curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
    -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"
  ```

  ```bash Recommendations API theme={null}
  # No Authorization header required — widget ID acts as the credential
  curl -X POST "https://eu1-recommendations.doofinder.com/api/widget/{widget_id}" \
    -H "Content-Type: application/json" \
    -d '{"current_url": "https://shop.example.com/products/shoes"}'
  ```
</CodeGroup>

See the full [Authentication guide](/introduction/authentication) for JWT tokens and zone-specific key formats.

## Common Error Codes

| Code  | Meaning                                             |
| ----- | --------------------------------------------------- |
| `400` | Bad Request — invalid parameters                    |
| `401` | Unauthorized — missing or invalid API key           |
| `403` | Forbidden — access denied (IP or origin blocked)    |
| `404` | Not Found — resource does not exist                 |
| `413` | Payload Too Large — request body exceeds 8 MB       |
| `422` | Unprocessable Entity — batch size exceeds 100 items |
| `429` | Too Many Requests — rate limit exceeded (20 req/s)  |

See the [Error Reference](/introduction/errors) for full details.