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

Collections

A collection is a named set of documents with a schema. You search one collection at a time (with SQL you name it in FROM), and you create, size and delete data per collection. Collections are isolated: no query can reach another organization's data or even another collection you have no role on.

#Names

A collection name starts with a lowercase letter and then uses only lowercase letters, digits and underscores: ^[a-z][a-z0-9_]*$.

Names are unique within an organization. A name that breaks the rule is rejected with 400 invalid_collection_name; creating one that already exists answers 409 already_exists.

#Create a collection

Creating a collection needs the admin role. How many collections you can have depends on your plan: past it you get 403 limit_exceeded. See Pricing and Limits and errors.

curl -X PUT https://api.warpsearch.io/v1/collections/books \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Book catalog",
    "class": "search",
    "labels": {"team": "catalog", "env": "prod"},
    "metadata": {"team": "catalog"},
    "mappings": {
      "properties": {
        "title":     {"type": "text"},
        "genre":     {"type": "keyword"},
        "year":      {"type": "integer"},
        "embedding": {"type": "dense_vector", "dims": 384, "similarity": "cosine"}
      }
    }
  }'

The body is optional, and so is every key in it:

You can also create collections in the management console under Collections, with the MCP create_collection tool, or implicitly through the Elasticsearch-compatible _bulk API when your key may create collections. Plain POST to /v1/collections/{c}/documents does not create a collection; it answers 404 for one that does not exist.

#Collection classes

A class tells WarpSearch what the collection is for, so it can pick storage and lifecycle defaults, most visibly how long the collection stays warm. It does not change the price per request or per GB. An unknown class answers 400 invalid_class.

A new collection can be written to straight away. Define the fields you care about up front: you can add fields later, but changing an existing field does not rewrite documents already stored. See Schemas and field types.

#List and describe

curl https://api.warpsearch.io/v1/collections \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY"

curl https://api.warpsearch.io/v1/collections/books \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY"

The first call lists the collections your key can see. A collection you hold no role on is not in the list, and asking for it answers 404, exactly as for a name that does not exist. The second returns one collection:

The console shows the same figures on each collection's page, and GET /v1/usage shows organization totals against your plan's limits.

#Change description, metadata and fields

PATCH changes the description, metadata and labels. Metadata and labels merge key by key, and setting a key to null removes it:

curl -X PATCH https://api.warpsearch.io/v1/collections/books \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": null, "owner": "search"}}'

To add fields, PUT /v1/collections/{c}/mapping takes a mapping with the new properties. Both calls need the admin role.

#Delete a collection

curl -X DELETE https://api.warpsearch.io/v1/collections/books \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY"

This deletes the collection and every document in it, and there is no undo. You can then create a collection with the same name from scratch. Deleting needs the admin role.

Coming soon: opening and closing a collection at runtime, to pause a collection without deleting it.

#Idle collections and cold starts

WarpSearch does not keep compute attached to a collection nobody is using. After a period without requests the collection is unloaded to durable storage, and the next request loads it again.

While it loads, the request can answer 503 with code warming_up and a Retry-After header. Nothing is wrong and nothing is billed for the wait. Retry after the number of seconds in the header:

curl -i https://api.warpsearch.io/v1/collections/books/search \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "lucene", "query": "title:dune"}'
# HTTP/1.1 503 Service Unavailable
# Retry-After: 5
# {"code":"warming_up","detail":"the collection is loading; retry shortly", ...}

Small collections are ready within moments; large ones take longer. Build retry-with-backoff into any client that talks to a collection that may be idle, and see Pricing for keep-warm, which holds a collection ready. Free accounts do not include keep-warm.

A free collection that is not queried or written for 30 days is deleted, and its mapping is kept so you can create it again; see Pricing.

#Roles on collections

Your API key's role decides what you can do with a collection:

A role that is too low answers 403 forbidden with a message naming the role you need. More in API keys, roles and rate limits.

#Gotchas

• Sizes in doc_count and size_bytes are cached, not live.
• Collection names cannot be changed. To rename, create a new collection and reload your data.
• Collections created in your organization are yours alone; there is no shared or public collection.
• The same name can exist in different organizations without conflict.

View this page as Markdown