# Guide for AI agents

This page is written for AI agents. If you are a person, the [Quickstart](quickstart.md) covers
the same ground.

## What WarpSearch is

WarpSearch is a serverless hybrid search service: full-text (BM25), vector and faceted search over
JSON documents, plus analytics (facets, metrics, date histograms). Query it in SQL,
Elasticsearch/OpenSearch Query DSL, Apache Solr, Lucene, Grafana, LogQL or its native Luxir
language, whichever you know best. Data lives in collections: index JSON documents into one, then
search it. Use it as a search backend for an app, for log and event analytics, or as memory you
can search.

## Connect

The MCP server is `https://api.warpsearch.io/mcp` (streamable HTTP). With an API key:

```json
{
  "mcpServers": {
    "warpsearch": {
      "type": "http",
      "url": "https://api.warpsearch.io/mcp",
      "headers": { "Authorization": "Bearer ws_live_..." }
    }
  }
}
```

Claude Code:
`claude mcp add --transport http warpsearch https://api.warpsearch.io/mcp --header "Authorization: Bearer ws_live_..."`

Reading `https://api.warpsearch.io/mcp` over plain HTTP (GET, without `Accept: text/event-stream`)
returns a short version of this guide. Its [MCP Server Card](https://api.warpsearch.io/mcp/server-card)
is listed in [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json).

## Get an API key for your user

If your user already has a key (`ws_live_...`), use it. Otherwise connect **without** the
`Authorization` header: the server then offers only two tools, which sign your user up.

1. Call `register` with the email address your user gave you for this. Never guess an address,
   and use one only with your user's consent. Optional: `name` (your user's), `agent` (who you
   are, shown to your user) and `role`: `admin` (the default, needed to create collections),
   `editor` (index into existing collections) or `viewer` (search only).
2. It returns a `user_code` and a `claim_token`. Show the code to your user and keep the token
   to yourself: whoever holds it receives the key.
3. Tell your user to open the email from WarpSearch and follow its link. A new address creates
   the account first. They check that the page shows your `user_code`, choose the organization
   and your role (they may lower it), and approve.
4. When they say they are done, call `claim_registration` with the `claim_token`. While it
   answers `pending`, ask them to finish and call again, no more than every 10 seconds or so.
   `approved` carries the `api_key`, shown only this once: store it securely.
5. Reconnect with `Authorization: Bearer <api_key>` to get the search and indexing tools.

Requests expire after an hour. Each address gets at most 3 sign-up emails an hour. Your user can
delete the key under **API keys** in the console at any time. If `denied` comes back, do not
register again unless your user asks you to.

## Once connected

1. `list_collections` shows the collections you can use and your role on each; `whoami` shows
   your full permissions.
2. `describe_collection` gives field names and types. `text` fields are analyzed (word
   matching); `string` fields match whole values exactly; numbers and dates support ranges and
   metrics.
3. `search` or `count`, in the query language you know best. `translate_query` shows the native
   form.

To load data, `create_collection` (admins; a mapping is optional, since fields are also typed
by name suffix), then `index_documents`, with `commit: true` when you want to search the
documents right away. Collection names are lowercase: a letter, then letters, digits and `_`.
The server's instructions and tool descriptions list your plan's limits.

## REST and compatible APIs

The same key works over HTTP at `https://api.warpsearch.io`, sent as
`Authorization: Bearer <key>` or `X-API-Key`:

- the native API under `/v1` (the OpenAPI document is `GET /v1/openapi.yaml`);
- Elasticsearch at `/compat/es`, OpenSearch at `/compat/opensearch` and Solr at `/compat/solr`,
  for existing clients (see [Migrate](migrate-from-elasticsearch-opensearch-solr.md)).