SemanticSearch API

📤 Step 1: Create Your Documents (JSON)

First, prepare your documents as a JSON file. Each document needs:

• id: Unique identifier
• title: Name of the document
• content: The actual text to search (keywords, descriptions, etc)
• keywords: Optional list of related terms
• metadata: Optional extra data (styling, state, etc)

{
  "documents": [
    {
      "id": "part-001",
      "title": "Charge System",
      "content": "solar panels energy reactor battery charging power recharge fuel cells electricity boost capacitor voltage amp watt",
      "keywords": ["charge", "recharge", "energy", "power", "battery", "solar", "electricity", "fuel", "boost", "reactor"],
      "metadata": {"css_class": "mode-charging", "state": "idle"}
    },
    {
      "id": "part-002",
      "title": "Flight System",
      "content": "thruster engine propulsion fly speed boost travel navigate rocket jet turbine accelerate velocity motion movement",
      "keywords": ["fly", "flight", "speed", "boost", "travel", "navigate", "move", "jet", "rocket", "propulsion"],
      "metadata": {"css_class": "mode-flying", "state": "active"}
    },
    {
      "id": "part-003",
      "title": "Stealth System",
      "content": "cloak invisibility hide camouflage stealth radar ghost disappear vanish disguise shadow sneak silent undetectable",
      "keywords": ["stealth", "hide", "invisible", "cloak", "camouflage", "ghost", "disappear", "vanish", "sneak", "silent"],
      "metadata": {"css_class": "mode-stealth", "state": "hidden"}
    },
    {
      "id": "part-004",
      "title": "Attack System",
      "content": "laser cannon weapon shoot fire attack combat strike offensive destroy blast hit target aim damage hurt",
      "keywords": ["attack", "shoot", "fire", "weapon", "laser", "combat", "strike", "destroy", "blast", "offensive"],
      "metadata": {"css_class": "mode-attack", "state": "offensive"}
    },
    {
      "id": "part-005",
      "title": "Defense System",
      "content": "shield barrier protect defense guard armor block deflect safe secure immunity resistance fortify wall protection",
      "keywords": ["shield", "protect", "defense", "guard", "armor", "block", "safe", "barrier", "secure", "deflect"],
      "metadata": {"css_class": "mode-shield", "state": "defensive"}
    },
    {
      "id": "part-006",
      "title": "Scan System",
      "content": "radar scanner detect analyze search scan probe sensor identify inspect examine investigate explore discover find see look watch observe",
      "keywords": ["scan", "search", "detect", "radar", "sensor", "analyze", "find", "probe", "inspect", "explore", "see", "look", "watch", "observe"],
      "metadata": {"css_class": "mode-scanning", "state": "active"}
    },
    {
      "id": "part-007",
      "title": "Repair System",
      "content": "repair fix heal restore maintenance regenerate recover rebuild patch mend cure treatment restore refurbish",
      "keywords": ["repair", "fix", "heal", "restore", "maintenance", "recover", "regenerate", "rebuild", "patch", "mend"],
      "metadata": {"css_class": "mode-repair", "state": "standby"}
    }
  ]
}

💡 Tip
ReadyAPI combines three fields to find matches:

1. Content field: This is the primary search field. It's converted into AI embeddings that understand meaning. Include descriptive text, features, specifications, and anything customers might ask about.
2. Title field: Gets a relevance boost if it matches the search. Used for exact and partial matches.
3. Keywords field: Optional but helpful. Provides hints about the document's topic.

🚀 Step 2: Send Documents to ReadyAPI

Use your API Key to upload the documents. ReadyAPI will process and index them instantly.

curl -X POST https://readyapi.net/api/v1/documents/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @documents.json

{
  "success": true,
  "message": "Successfully uploaded 7 documents",
  "uploaded_count": 7,
  "failed_count": 0
}

✅ Done! Your 7 spaceship systems are now indexed and searchable. You only need to do this once!

🔍 Step 3: Search with Natural Language (No Keywords Required!)

Now you can ask questions in plain English. ReadyAPI understands meaning, not just keywords.

🧠 How it works: ReadyAPI uses advanced AI (Arctic embeddings) to understand what you mean, not just what keywords you use. So "get somewhere far away quickly" understands you need speed and distance, and finds the Flight System!

🧠 How it works: ReadyAPI uses advanced AI (Arctic embeddings) to understand what you mean, not just what keywords you use. So "get somewhere far away quickly" understands you need speed and distance, and finds the Warp System!

Now make the API call to search:

curl -X POST https://readyapi.net/api/v1/search/query \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need to get somewhere far away quickly",
    "top_k": 3
  }'

curl -X POST https://readyapi.net/api/v1/search/query \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need to get somewhere far away quickly",
    "top_k": 3,
    "filters": {
      "metadata.state": "active"
    }
  }'

🎯 Optional Filters: You can add filters to narrow down results by metadata. Filters give you precise control over which documents are returned.

✅ Step 4: Get Ranked Results

ReadyAPI returns the most relevant documents, ranked by similarity.

{
  "results": [
    {
      "id": "part-002",
      "title": "Flight System",
      "score": 0.52,
      "content": "thruster engine propulsion fly speed boost travel navigate..."
    },
    {
      "id": "part-003",
      "title": "Stealth System",
      "score": 0.48,
      "content": "cloak invisibility hide camouflage stealth radar ghost..."
    },
    {
      "id": "part-006",
      "title": "Scan System",
      "score": 0.46,
      "content": "radar scanner detect analyze search..."
    }
  ],
  "count": 3,
  "processing_ms": 124
}

🎯 That's It! You're Ready

Three simple steps: Create JSON → Upload Documents → Search Naturally. No complex setup, just ask in plain language and get smart results.