References

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

Quick Start

Get your first API call running in under 5 minutes.

Search API

Query indexed items, get autocomplete suggestions, run image search, and log user interactions in real time.

Management API

Create and configure search engines, manage indices, and push or update items programmatically.

Stats API

Retrieve analytics — sessions, top searches, click-through rates, conversion data, and more.

Recommendations API

Deliver personalized product recommendations powered by Doofinder’s recommendation engine.

Category Merchandising API

Configure and manage category-level search rules and boost strategies.

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`

Your search zone is shown in the Doofinder Admin Panel. The zone prefix on API keys (e.g. eu1-ab46030x...) is optional — the zone is determined by the hostname you call.

Authentication at a Glance

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

curl "https://eu1-search.doofinder.com/6/{hashid}/_search?query=shoes" \
  -H "Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07"

curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
  -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"

# 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"}'

See the full Authentication guide 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 for full details.

​References

Quick Start

Search API

Management API

Stats API

Recommendations API

Category Merchandising API

​Architecture Overview

​Authentication at a Glance

​Common Error Codes

References

Architecture Overview

Authentication at a Glance

Common Error Codes