API Overview

Flapjack exposes an Algolia-compatible REST API. If you’ve used Algolia’s API, you already know Flapjack’s API.

Base URL

• Self-hosted: http://localhost:7700 (or your configured address)
• Flapjack Cloud: https://<your-ip>:7700 (shown in dashboard)

Authentication

All write and search endpoints require two headers:

X-Algolia-Application-Id: flapjack
X-Algolia-API-Key: YOUR_ADMIN_KEY

The application ID is always flapjack. The API key is the admin key you configured (self-hosted) or the one shown in your dashboard (Cloud).

Unauthenticated endpoints: /health and /stats do not require auth headers.

Endpoints

Health & Stats

Method	Path	Auth	Description
GET	/health	No	Health check
GET	/stats	No	Database size stats

Search

Method	Path	Auth	Description
POST	/1/indexes/{indexName}/query	Yes	Search an index
POST	/1/indexes/*/queries	Yes	Search multiple indices

Indexing

Method	Path	Auth	Description
POST	/1/indexes/{indexName}/batch	Yes	Batch operations
POST	/1/indexes/{indexName}	Yes	Add object
PUT	/1/indexes/{indexName}/{objectID}	Yes	Update object
DELETE	/1/indexes/{indexName}/{objectID}	Yes	Delete object
GET	/1/indexes/{indexName}/{objectID}	Yes	Get object

Index Management

Method	Path	Auth	Description
GET	/1/indexes	Yes	List indices
DELETE	/1/indexes/{indexName}	Yes	Delete index
POST	/1/indexes/{indexName}/clear	Yes	Clear objects

Settings

Method	Path	Auth	Description
GET	/1/indexes/{indexName}/settings	Yes	Get settings
PUT	/1/indexes/{indexName}/settings	Yes	Update settings

Response format

All endpoints return JSON. Search responses follow the Algolia format:

{
  "hits": [...],
  "nbHits": 100,
  "page": 0,
  "hitsPerPage": 20,
  "nbPages": 5,
  "processingTimeMS": 1,
  "query": "search term"
}

Write operations return:

{
  "taskID": 12345,
  "objectIDs": ["id1", "id2"]
}

Error responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "message": "Description of the error",
  "status": 400
}

Status	Meaning
400	Bad request (invalid JSON, missing fields)
401	Unauthorized (missing or invalid API key)
404	Index or object not found
500	Internal server error