Semantic Search

POST /v1/buckets
{
  "bucket_name": "knowledge-base",
  "schema": {
    "properties": {
      "title": { "type": "text", "required": true },
      "content": { "type": "text", "required": true },
      "category": { "type": "text" },
      "tags": { "type": "array" }
    }
  }
}

POST /v1/collections
{
  "collection_name": "docs-search",
  "source": { "type": "bucket", "bucket_id": "bkt_kb" },
  "feature_extractor": {
    "feature_extractor_name": "text_extractor",
    "version": "v1",
    "input_mappings": { "text": "content" },
    "parameters": {
      "model": "multilingual-e5-large-instruct",
      "chunk_strategy": "sentence",
      "chunk_size": 512,
      "chunk_overlap": 50
    },
    "field_passthrough": [
      { "source_path": "title" },
      { "source_path": "category" },
      { "source_path": "tags" }
    ]
  }
}

POST /v1/buckets/{bucket_id}/objects
{
  "key_prefix": "/docs/api",
  "metadata": {
    "title": "Authentication Guide",
    "content": "Mixpeek uses Bearer token authentication...",
    "category": "getting-started",
    "tags": ["auth", "security"]
  }
}

POST /v1/retrievers
{
  "retriever_name": "docs-search",
  "collection_ids": ["col_docs"],
  "input_schema": {
    "properties": {
      "query": { "type": "text", "required": true }
    }
  },
  "stages": [
    {
      "stage_name": "knn_search",
      "version": "v1",
      "parameters": {
        "feature_address": "mixpeek://text_extractor@v1/text_embedding",
        "input_mapping": { "text": "query" },
        "limit": 50
      }
    }
  ]
}

POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": { "query": "how do I authenticate API requests?" },
  "limit": 10
}

{
  "stages": [
    {
      "stage_name": "hybrid_search",
      "version": "v1",
      "parameters": {
        "queries": [
          {
            "feature_address": "mixpeek://text_extractor@v1/text_embedding",
            "input_mapping": { "text": "query" },
            "weight": 0.7
          },
          {
            "feature_address": "mixpeek://text_extractor@v1/bm25_sparse",
            "input_mapping": { "text": "query" },
            "weight": 0.3
          }
        ],
        "fusion_method": "rrf",
        "limit": 50
      }
    }
  ]
}

{
  "stages": [
    {
      "stage_name": "filter",
      "version": "v1",
      "parameters": {
        "filters": {
          "operator": "and",
          "conditions": [
            {
              "field": "metadata.category",
              "operator": "eq",
              "value": "getting-started"
            }
          ]
        }
      }
    },
    {
      "stage_name": "knn_search",
      "version": "v1",
      "parameters": {
        "feature_address": "mixpeek://text_extractor@v1/text_embedding",
        "input_mapping": { "text": "query" },
        "limit": 50
      }
    }
  ]
}

{
  "stages": [
    {
      "stage_name": "knn_search",
      "parameters": { "limit": 100 }
    },
    {
      "stage_name": "rerank",
      "version": "v1",
      "parameters": {
        "model": "cross-encoder/ms-marco-MiniLM-L-12-v2",
        "input_mapping": {
          "query": "query",
          "document": "metadata.content"
        },
        "top_k": 20
      }
    }
  ]
}