Migrate from Algolia

Flapjack implements the Algolia REST API. Your existing code, client libraries, and InstantSearch.js setup work with Flapjack — you just change where requests are sent.

What stays the same

• API paths: /1/indexes/{indexName}/query, /1/indexes/{indexName}/batch, etc.
• Auth headers: X-Algolia-Application-Id and X-Algolia-API-Key
• Request format: Same JSON bodies for search and indexing
• Response format: hits, nbHits, processingTimeMS, query, params
• Client libraries: The official algoliasearch JavaScript client works with Flapjack
• InstantSearch.js: Works out of the box with a custom host

Step 1: Start Flapjack

Self-hosted:

docker run -d -p 7700:7700 \
  -e FLAPJACK_ADMIN_KEY=your-secret-key \
  -v flapjack-data:/var/lib/flapjack \
  ghcr.io/flapjack-search/flapjack

Or use Flapjack Cloud for a managed instance.

Step 2: Update your client configuration

JavaScript (algoliasearch)

Before (Algolia):

import algoliasearch from 'algoliasearch';

const client = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY');
const index = client.initIndex('movies');

After (Flapjack):

import { liteClient as algoliasearch } from 'algoliasearch/lite';

const client = algoliasearch('flapjack', 'YOUR_FLAPJACK_ADMIN_KEY', {
  hosts: [{ url: 'localhost:7700', protocol: 'http' }],
});

That’s it. One line changes: the host. All your index.search(), index.saveObjects(), and index.getObject() calls work the same way.

InstantSearch.js

Before:

const searchClient = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY');

After:

const searchClient = algoliasearch('flapjack', 'YOUR_FLAPJACK_ADMIN_KEY', {
  hosts: [{ url: 'localhost:7700', protocol: 'http' }],
});

Everything else — searchBox, hits, refinementList, pagination — works unchanged. See the full InstantSearch.js guide.

Python

from algoliasearch.search.client import SearchClientSync

# Create client pointing at Flapjack instead of Algolia
client = SearchClientSync.create(
    app_id="flapjack",
    api_key="YOUR_FLAPJACK_ADMIN_KEY",
)
# Override the host
client._transporter._hosts = [Host("localhost", 7700, "http")]

cURL

Just change the URL and credentials:

# Before (Algolia)
curl -X POST 'https://YOUR_APP_ID-dsn.algolia.net/1/indexes/movies/query' \
  -H 'X-Algolia-Application-Id: YOUR_APP_ID' \
  -H 'X-Algolia-API-Key: YOUR_API_KEY' \
  -d '{"query":"matrix"}'

# After (Flapjack)
curl -X POST 'http://localhost:7700/1/indexes/movies/query' \
  -H 'X-Algolia-Application-Id: flapjack' \
  -H 'X-Algolia-API-Key: YOUR_FLAPJACK_ADMIN_KEY' \
  -d '{"query":"matrix"}'

Step 3: Export and import your data

Export your data from Algolia using their dashboard or API, then import it into Flapjack:

curl -X POST 'http://localhost:7700/1/indexes/movies/batch' \
  -H 'X-Algolia-Application-Id: flapjack' \
  -H 'X-Algolia-API-Key: YOUR_FLAPJACK_ADMIN_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {"action": "addObject", "body": {"objectID": "1", "title": "The Matrix", "year": 1999}},
      {"action": "addObject", "body": {"objectID": "2", "title": "Inception", "year": 2010}}
    ]
  }'

The batch API supports the same actions as Algolia: addObject, updateObject, deleteObject, clear.

Tip

For large datasets, send documents in batches of 1,000. The batch endpoint handles them efficiently.

Step 4: Verify

curl -X POST 'http://localhost:7700/1/indexes/movies/query' \
  -H 'X-Algolia-Application-Id: flapjack' \
  -H 'X-Algolia-API-Key: YOUR_FLAPJACK_ADMIN_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query": "matrix"}'

You should see the same response format you’re used to from Algolia:

{
  "hits": [
    {
      "objectID": "1",
      "title": "The Matrix",
      "year": 1999,
      "_highlightResult": {
        "title": {
          "value": "The <em>Matrix</em>",
          "matchLevel": "full"
        }
      }
    }
  ],
  "nbHits": 1,
  "page": 0,
  "hitsPerPage": 20,
  "processingTimeMS": 0,
  "query": "matrix"
}

Compatibility reference

Feature	Status
Search (/1/indexes/{index}/query)	Supported
Multi-index search (/1/indexes/*/queries)	Supported
Batch indexing (/1/indexes/{index}/batch)	Supported
Get/delete individual objects	Supported
Index settings	Supported
Highlighting	Supported
Faceted search	Supported
Filtering	Supported
Pagination	Supported
Geo search	Planned
Synonyms	Planned
Query Rules	Planned
A/B Testing	Not planned
Personalization	Not planned

Features marked “Not planned” are Algolia-specific SaaS features. Flapjack focuses on the core search functionality that the vast majority of Algolia customers actually use.

Why migrate?

• Cost: Algolia bills per search operation and scales aggressively. Flapjack is free (self-hosted) or flat-fee (Cloud).
• Data ownership: Your data stays on your infrastructure. No vendor lock-in.
• Simplicity: Single binary, no cluster management, no configuration servers.
• Open source: MIT licensed. Audit, fork, modify, contribute.