Quickstart

From signup to first search result in five minutes. Self-tested — copy any block, swap your key, and the response is exactly what's documented.

This guide takes you from zero to a working search in five minutes. Every curl block is copy-paste working — they've been run against the live API on the same day this doc was published.

# 0. Sanity check the network (10 seconds)

Confirm your laptop can reach the API before fighting with auth.

curl https://api.skryx.io/v1/health

Expected response:

{ "status": "operational", "version": "1.0",
  "services": { "api": "ok", "search": "ok", "docs": "https://app.skryx.io/docs" },
  "now": "2026-05-24T10:21:09+00:00" }

No Authorization header needed — /v1/health is public.

# 1. Sign up and grab your key

Sign up at app.skryx.io. When you land on the dashboard:

  1. Open API keys in the sidebar.
  2. Click Create key, pick the admin scope, name it quickstart.
  3. Copy the value that starts with sk_live_. The full key is shown once — store it in your environment.
export SKRYX_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx

# 2. Create an index

An index is a logical collection of documents you want to search. Auto-Pilot is enabled by default — when you push your first batch of 50+ documents, Skryx automatically detects schema, language, domain, synonyms, ranking rules, and enables semantic search. The schema you declare here is preserved.

curl -X POST https://api.skryx.io/v1/indexes \
  -H "Authorization: Bearer $SKRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "schema": {
      "fields": [
        { "name": "title",    "type": "string"                },
        { "name": "brand",    "type": "string", "facet": true },
        { "name": "category", "type": "string", "facet": true },
        { "name": "price",    "type": "float",  "facet": true },
        { "name": "in_stock", "type": "bool",   "facet": true }
      ]
    }
  }'

# 3. Add documents

Push documents in batches of up to 1,000. Skryx upserts by id, so you can re-push the same payload to update.

curl -X POST https://api.skryx.io/v1/indexes/products/documents/batch \
  -H "Authorization: Bearer $SKRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "1", "title": "Sony WH-1000XM5",         "brand": "Sony",  "category": "Headphones", "price": 379, "in_stock": true  },
      { "id": "2", "title": "Bose QuietComfort Ultra", "brand": "Bose",  "category": "Headphones", "price": 449, "in_stock": true  },
      { "id": "3", "title": "AirPods Pro 2 USB-C",     "brand": "Apple", "category": "Headphones", "price": 279, "in_stock": false }
    ]
  }'

Two equivalent endpoints exist for searching: /query (the original name) and /search (the alias most integrations reach for first). Both accept the same body. The simplest possible search:

curl -X POST https://api.skryx.io/v1/indexes/products/search \
  -H "Authorization: Bearer $SKRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "sony" }'

You get back the Skryx-native response shape at the top level:

{
  "hits": [
    {
      "document": { "id": "1", "title": "Sony WH-1000XM5", "brand": "Sony", "category": "Headphones", "price": 379, "in_stock": true },
      "match_type": "keyword",
      "text_match": 578730054645712906
    }
  ],
  "found": 1,
  "page": 1,
  "per_page": 10,
  "total_pages": 1,
  "facets": {},
  "search_time_ms": 8,
  "ai_enhanced": false,
  "search_mode": "keyword"
}

Want results for natural-language queries like "noise cancelling headphones for travel"? Enable semantic search on the index (settings page, or POST /v1/indexes/{name}/semantic-search/enable) and set search_mode: "auto" or "semantic" — the AI matches by meaning, not just keywords. Auto-Pilot turns this on for you when you add 50+ documents.

# Filters and facets — Skryx-native shape

You don't need to learn the underlying engine's filter syntax. Pass filters as a dict of { field: [values] } and facets as a string array:

curl -X POST https://api.skryx.io/v1/indexes/products/search \
  -H "Authorization: Bearer $SKRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "headphones",
    "per_page": 20,
    "filters": { "in_stock": [true] },
    "facets": ["brand", "category"],
    "sort": "price:asc"
  }'

Response includes a flat facets dict suitable for direct rendering:

{
  "hits": [ ... ],
  "found": 2,
  "facets": {
    "brand":    { "Sony": 1, "Bose": 1 },
    "category": { "Headphones": 2 }
  },
  "search_time_ms": 11
}

# Letting Skryx pick the search mode

The default search_mode is auto — a small router picks keyword for SKU / single-word / brand+model queries, semantic for natural-language questions, and hybrid for the rest. Override per request if needed:

# Force semantic AI search (slower, costlier, better for "headphones for travel")
curl -X POST https://api.skryx.io/v1/indexes/products/search \
  -H "Authorization: Bearer $SKRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "headphones for travel", "search_mode": "semantic" }'

ai_enhanced: true appears in the response when AI was involved (semantic / hybrid mode, query rewriting, or a typo correction).

esc