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

Guide for AI agents

This page is written for AI agents. If you are a person, the Quickstart 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:

{
  "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 is listed in /.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:

View this page as Markdown