Indexes

Indexes hold your documents and search configuration. Each index has a unique identifier (uid) and an optional primary key that identifies each document. Indexes are automatically scoped to your project. Creating an index through the public API requires a project-scoped admin key; org-scoped keys are for cross-project read/search workflows.

GET/v1/indexes

List all indexes in your project.

Auth admin or search keyReturns 200
Response
{
  "results": [
    {
      "uid": "products",
      "primaryKey": "id",
      "createdAt": "2025-01-15T08:30:00Z",
      "updatedAt": "2025-01-15T09:12:00Z"
    }
  ]
}
POST/v1/indexes

Create a new index with a project-scoped admin key so dashboard, usage, and analytics attribution stay attached.

Auth admin key onlyReturns 202
Request body
{
  "uid": "products",
  "primaryKey": "id",        // optional
  "engine": "meilisearch"    // optional
}
Response
{
  "taskUid": 1,
  "indexUid": "products",
  "status": "enqueued"
}

Per-index engine routing

If engine is omitted, the project default is used. If it matches the project default, Headband uses that project's custom engine config. If it differs, the current API uses platform defaults for that engine. Create separate projects when you need BYOE configs for multiple engines until per-index custom configs are exposed.
GET/v1/indexes/:uid

Get information about a single index.

Auth admin or search keyReturns 200
Response
{
  "uid": "products",
  "primaryKey": "id",
  "createdAt": "2025-01-15T08:30:00Z",
  "updatedAt": "2025-01-15T09:12:00Z"
}
DELETE/v1/indexes/:uid

Delete an index and all its documents.

Auth admin key onlyReturns 202
Response
{
  "taskUid": 4,
  "indexUid": "products",
  "status": "enqueued"
}