API Reference

Welcome to the **Misbar Search Engine** API documentation. This guide will help you integrate search capabilities into your application using our high-performance, multi-tenant search engine.

Base URL

Your unique API endpoint can be found in the **Settings** section of your dashboard.

http://your-domain.com/api View in Settings →

Authentication

Most endpoints require a **Bearer Token**. You must include it in your request headers:

Authorization: Bearer YOUR_API_TOKEN

*Note: All tokens provided by the system (Master and API) are Base64 encoded strings. Use the entire string as provided.*

01 Account & Authentication

POST /api/register

Create a new user account to start managing your indices.

{
  "email": "dev@example.com",
  "password": "your_secure_password"
}

POST /api/create-token

{
  "email": "dev@example.com",
  "password": "your_secure_password"
}

POST /api/update-profile

Update your account details. Requires **Master Token**.

{
  "current_password": "your_current_password",
  "email": "new_email@example.com",
  "new_password": "new_secure_password"
}

POST /api/tokens

Create a specific API token for indexing and searching. Requires **Master Token**.

{
  "token_name": "Mobile App",
  "type": "both" // read, write, or both
}

GET /api/tokens

Retrieve all API tokens generated by the user. Requires **Master Token**.

POST /api/permissions

Assign or remove index permissions for an API token. Requires **Master Token**.

{
  "token": "API_TOKEN",
  "index_name": ["products", "categories"] 
}

DELETE /api/permissions

02 Index Management

GET /api/indices

Get a list of all indices owned by the current user. Requires **Master Token**.

POST /api/index/rename

Change the display name of an index. Requires **Master Token**.

{
  "old_name": "products",
  "new_name": "store_items"
}

POST /api/index

Add documents to an index storage. Requires **API Token**.

{
  "index_name": "products",
  "data": [
    { "id": "1", "title": "iPhone 15", "category": "Electronics" },
    { "id": "2", "title": "MacBook Pro", "category": "Electronics" }
  ]
}

POST /api/index/upload

Upload a JSON file directly to server storage. Requires **API Token**.

Multipart Form Data

index_name: Target index
file: The .json file

POST /api/index/process

Process pending documents and make them searchable. Returns **NDJSON** stream.

{
  "index_name": "products",
  "limit": 1000
}

POST /api/index/reindex

Reset all documents in an index to "pending" status. Requires **API Token**.

GET /api/browse/{index_name}

Retrieve all documents in an index. Requires **API Token**.

GET /api/fields/{index_name}

Get a list of all fields (keys) present in an index. Requires **API Token**.

GET /api/roots/{index_name}

Explore morphological roots and their original words. Requires **API Token**.

GET /api/root-words/{index_name}?root=علم

03 Searching

GET /api/search

Search through your indexed data with advanced linguistic support. Requires **API Token**.

Parameter	Type	Description
index_name	string	Target index name (Required)
q	string	Search query string (Required)
mode	string	`smart`, `exact`, `stem`, `root`
boolean	bool	Enable AND, OR, NOT operators
ids_only	bool	Return only IDs (Bypasses storage)
filter[key]	string	Exact match filter
highlight	string	Comma-separated fields to highlight
snippet	string	Comma-separated fields for snippets

IDs Only Response

{
  "status": "success",
  "hits": ["1", "5", "12", "45"],
  "total": 4,
  "execution_time": "0.0012s"
}

04 Advanced Strategy

STEMUR Strategy

Misbar uses a sophisticated **Multi-Layer Indexing Strategy** to ensure high relevance and linguistic accuracy for Arabic and Urdu.

Layer 1

Exact Match

Original normalized word. Weighted x3.

Layer 2

Stem Match

Concept/stem after removing affixes. Weighted x2.

Layer 3

Root Match

Morphological root (STEMUR). Weighted x1.

GET /api/index/export/{name}

Download a ZIP file containing the full-text index and document storage.

POST /api/index/import

Restore an index from a previously exported ZIP file.

GET /api/stats/{index_name}

Get detailed information about an index size and document count.

05 Error Handling

{
  "status": "error",
  "message": "Detailed error message here"
}

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Server Error

06 Best Practices

Tokens Security

Use Master Token only for admin tasks. Use API Tokens for daily operations.

Batch Indexing

Send documents in batches (500-1000) for optimal performance.

Unique IDs

Ensure every document has a unique `id` field to prevent overwrites.

Concurrency

The system supports searching while indexing is in progress.