For AI agents: this page is also available as Markdown at /docs/api-reference.md. Every docs page is: add .md to its URL. llms.txt lists them all.

REST API reference

The native API lives under /v1 at https://api.warpsearch.io. The complete, machine-readable description is the OpenAPI document at https://api.warpsearch.io/v1/openapi.yaml. This page is the short version.

Authentication

Every request authenticates. Nothing is served anonymously. Send your API key (ws_live_...) in any of these forms:

Form Example
Bearer token Authorization: Bearer ws_live_...
Key header X-API-Key: ws_live_...
ApiKey scheme Authorization: ApiKey ws_live_...
HTTP Basic the key as the password, with any username

Elasticsearch clients can also send their base64 id:secret form. Roles are monitor, read, write and admin, and a key sees only the collections it holds a role on. See Access control. GET /v1/auth/me shows who you are and what you may do.

Routes

Method and path Role Purpose
POST /v1/collections/{collection}/search read Search a collection. Add ?format=es for an Elasticsearch-shaped response.
GET /v1/collections/{collection}/search read Quick search with q, limit, offset, sort and fields.
POST /v1/search read Search where the collection comes from the body, or from FROM in SQL.
POST /v1/translate read Show the native form of a query without running it.
POST /v1/collections/{collection}/count read Count matching documents.
GET /v1/collections monitor List the collections you can access.
PUT /v1/collections/{collection} admin, plus permission to create collections Create a collection, with an optional mapping, description and metadata.
GET /v1/collections/{collection} monitor Describe a collection and its fields.
PATCH /v1/collections/{collection} admin Change the description and metadata.
DELETE /v1/collections/{collection} admin Delete a collection and its documents.
PUT /v1/collections/{collection}/mapping admin Add or replace field definitions.
POST /v1/collections/{collection}/refresh write Make pending writes searchable.
POST /v1/collections/{collection}/documents write Index documents (JSON array, {"docs": [...]} or NDJSON). Add ?commit=true to search them right away.
GET /v1/collections/{collection}/documents/{id} read Get one document.
DELETE /v1/collections/{collection}/documents/{id} write Delete one document.
POST /v1/collections/{collection}/documents/_delete write Delete several documents by id.
GET /v1/usage needs the view usage permission Your usage counters and plan limits.
GET /v1/auth/me any The caller, its permissions and its role on each collection.

A search request names its language (sql, es, lucene, grafana, logql, luxir or solr) and carries the query, plus optional filters, facets, metrics, sort, limit, offset, fields and time_range. See Searching and Query languages.

Conventions

Compatible APIs and agents

The same key works on the compatible APIs, so existing clients keep working:

Agents connect to the MCP server at https://api.warpsearch.io/mcp. See the Guide for AI agents.

View this page as Markdown