Skip to content
Searchcraft Searchcraft
Vektron

Index Management

Index create/update/patch operations should only be used if you are using the self-hosted version of Searchcraft. Index operations for Searchcraft Cloud are managed via the Vektron UI.

API Endpoints

Section titled “API Endpoints”
  • GET /index Returns a list of all indexes.
  • GET /index/stats Returns document counts for every index on the instance.
  • GET /index/:index_name Returns the schema for an index.
  • GET /index/:index_name/stats Returns meta data about an index such as the number of documents.
  • POST /index Creates or updates an index. Expects a schema definition object in the request body. This will empty your index if it exists and has documents.
  • PATCH /index/:index_name Allows you to make a partial configuration change to an index schema without having to re-ingest all of your data. Updates are limited to search_fields, weight_multipliers, language, time_decay_field, auto_commit_delay, exclude_stop_words, enable_language_stemming, ingestion, ai_enabled, and ai settings. Unlike the other index endpoints, the payload values should not be nested inside an index object.
  • PUT /index/:index_name Replace the contents. Expects a schema definition object in the request body. Same payload as POST /index. If the index does not exist you will receive a 404.
  • DELETE /index/:index_name Deletes an index.

Auth Requirement

Section titled “Auth Requirement”

Requires an authentication key that has permissions to access the endpoint.

  • POST /index requires an admin key.
  • PATCH /index/:index_name and PUT /index/:index_name can use an ingest key for normal schema updates, including updates to the ai configuration block.
  • If a PATCH or PUT request includes ai_enabled, the caller must use an admin key with index-modification permissions.
  • New indexes default to ai_enabled: false unless an admin explicitly sets ai_enabled: true during creation.

Optional AI configuration

Section titled “Optional AI configuration”

The ai block is optional on an index schema.

If you omit ai, standard Searchcraft indexing and search continue to work normally, but AI-specific endpoints such as Search Result Summaries will not be available until AI configuration is added.

Searchcraft also stores a separate top-level ai_enabled master switch for each index. This flag is independent of the ai configuration and defaults to false for newly created indexes unless an admin explicitly turns it on.

  • ai_enabled controls whether AI-powered endpoints are available for the index.
  • The ai block stores the provider, credentials, and summary configuration details.
  • You can keep ai configured while setting ai_enabled to false.
  • For POST /index and PUT /index/:index_name, include ai_enabled and ai inside the nested index object.
  • For PATCH /index/:index_name, send ai_enabled and ai as top-level fields in the patch payload.
  • If a PATCH request omits ai, the existing AI configuration is preserved.
  • If a PATCH request includes ai, the existing AI configuration is replaced with the new ai object.
  • If a PATCH request omits ai_enabled, the existing ai_enabled value is preserved.
  • If a PUT request omits ai_enabled, the existing ai_enabled value is preserved.
  • Changing ai_enabled requires an admin key. Updating only ai can still be done with an ingest key.

AI master switch property

Section titled “AI master switch property”
  • ai_enabled - Optional boolean. Defaults to false for newly created indexes. When false, AI capabilities are reported as disabled for the index and POST /index/:index_name/search/summary will return a 400 response until an admin turns the switch on.

AI configuration properties

Section titled “AI configuration properties”
  • ai.llm_provider - Required when ai is present. Supported values are:
    • bedrock - AWS Bedrock. Requires llm_region.
    • llamacpp - llama.cpp server mode. Requires llm_base_url.
    • ollama - Ollama. No additional field is required.
    • openai - OpenAI or OpenAI-compatible APIs. Requires llm_api_key.
    • anthropic - Anthropic Claude. Requires llm_api_key.
    • google - Google Gemini. Requires llm_api_key.
    • xai - xAI (Grok). Requires llm_api_key.
    • mistral - Mistral AI. Requires llm_api_key.
  • ai.llm_region - Optional string. Required when llm_provider is bedrock.
  • ai.llm_base_url - Optional string. Used for Ollama, llama.cpp server mode, or OpenAI-compatible APIs. Required when llm_provider is llamacpp.
  • ai.llm_api_key - Optional string. Required when llm_provider is openai, anthropic, google, xai, or mistral.
  • ai.search_summary - Optional object. Configure this when you want to enable POST /index/:index_name/search/summary for the index.

Search summary properties

Section titled “Search summary properties”
  • ai.search_summary.model - Required non-empty string. The model identifier used to generate summaries.
  • ai.search_summary.role - Optional string. The system role/persona for the summary prompt. Defaults to a helpful assistant skilled at creating comprehensive summaries.
  • ai.search_summary.character_limit - Optional integer. Maximum character limit for the generated summary. Defaults to 500.
  • ai.search_summary.max_results - Optional integer. Maximum number of search results to include in the summary prompt. Defaults to 5.
  • ai.search_summary.document_trim_length - Optional integer. Maximum number of characters to include from each matched document. Defaults to 1000.
  • ai.search_summary.temperature - Optional number between 0.0 and 1.0. Controls response variability. Defaults to 0.2.
  • ai.search_summary.empty_state_message - Optional string. Returned when a summary search finds no results and no keyword rule overrides it. Supports ${searchTopic} placeholder replacement.
  • ai.search_summary.additional_prompt_instructions - Optional array of additional prompt instructions. Each item contains:
    • custom_instruction - Required string.
    • order - Required integer. Lower numbers are applied first.
  • ai.search_summary.keyword_rules - Optional array of keyword-based rules for modifying summary behavior. Each rule contains:
    • rule_name - Required string. Used to identify the rule in server logs. Has no effect on matching or summary behaviour.
    • detect_keywords - Required array of strings. Matching is case-insensitive and substring-based — a rule fires if any keyword in the array is found anywhere in the search term. For example, a keyword of "nutrition" would also match the query "malnutrition".
    • replacement_term - Optional string. When set, replaces the search term submitted to the search engine and used as the topic in the LLM prompt. The original search term is preserved only for display purposes.
    • custom_instruction - Optional string. Appended to the index-level additional_prompt_instructions when the rule matches.
    • empty_state_message - Optional string. Overrides the index-level empty_state_message when the rule matches and the search returns no results. Supports ${searchTopic} placeholder replacement.
    • order - Required integer. Lower numbers are evaluated first. The first matching rule wins and no further rules are evaluated.

Keyword rules are sorted by order and the first matching rule wins. See Search Result Summaries for endpoint behaviour details.

Schema creation

Section titled “Schema creation”

Payload to create an index on a self-hosted instance of Searchcraft. See the schema configuration reference for more information on the properties.

Example schema without AI

Section titled “Example schema without AI”

This example omits the optional ai block.

Because ai_enabled is omitted, the new index will also start with AI disabled.

{
  "index": {
    "auto_commit_delay": 1,
    "language": "en",
    "name": "creation_test",
    "search_fields": [
      "title",
      "body"
    ],
    "fields": {
      "id": {
        "type": "text",
        "required": true,
        "stored": true,
        "indexed": false
      },
      "created_at": {
        "type": "datetime",
        "fast": true,
        "stored": true,
        "indexed": true
      },
      "title": {
        "type": "text",
        "stored": true
      },
      "body": {
        "type": "text",
        "stored": true
      },
      "active": {
        "type": "bool",
        "fast": true,
        "stored": true
      },
      "rating": {
        "type": "f64",
        "stored": true,
        "fast": true
      },
      "reviews": {
        "type": "u64",
        "stored": true,
        "fast": true
      },
      "tags": {
        "type": "text",
        "stored": true,
        "multi": true
      },
      "category": {
        "type": "facet",
        "stored": true
      },
      "formats": {
        "type": "facet",
        "stored": true,
        "multi": true
      }
    },
    "weight_multipliers": {
      "title": 2,
      "body": 0.7
    }
  }
}

Example CURL request to create an index without AI

Section titled “Example CURL request to create an index without AI”
  • override_if_exists - Optional boolean value that dictates whether or not the POST request will override the existing index if it already exists. Defaults to false.
  • index - The index schema. See the schema configuration reference.
Terminal window
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "override_if_exists": true,
    "index": {
      "name": "creation_test",
      "search_fields": [
        "title",
        "body"
      ],
      "fields": {
        "id": {
          "type": "text",
          "required": true,
          "stored": true,
          "indexed": false
        },
        "created_at": {
          "type": "datetime",
          "fast": true,
          "stored": true,
          "indexed": true
        },
        "title": {
          "type": "text",
          "stored": true
        },
        "body": {
          "type": "text",
          "stored": true
        },
        "active": {
          "type": "bool",
          "fast": true,
          "stored": true
        },
        "rating": {
          "type": "f64",
          "stored": true,
          "fast": true
        },
        "reviews": {
          "type": "u64",
          "stored": true,
          "fast": true
        },
        "tags": {
          "type": "text",
          "stored": true,
          "multi": true
        },
        "category": {
          "type": "facet",
          "stored": true
        },
        "formats": {
          "type": "facet",
          "stored": true,
          "multi": true
        }
      },
      "weight_multipliers": {
        "title": 2,
        "body": 0.7
      }
    }
  }' \
  http://yoursearchcrafthost/index

Example CURL request to create an index with OpenAI summaries

Section titled “Example CURL request to create an index with OpenAI summaries”
Terminal window
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "override_if_exists": true,
    "index": {
      "name": "product_docs",
      "search_fields": [
        "title",
        "body"
      ],
      "fields": {
        "title": {
          "type": "text",
          "stored": true
        },
        "body": {
          "type": "text",
          "stored": true
        },
        "category": {
          "type": "facet",
          "stored": true
        }
      },
      "weight_multipliers": {
        "title": 2,
        "body": 0.8
      },
      "ai_enabled": true,
      "ai": {
        "llm_provider": "openai",
        "llm_api_key": "sk-your-api-key",
        "search_summary": {
          "model": "gpt-4o-mini",
          "role": "a helpful product documentation assistant",
          "character_limit": 600,
          "max_results": 5,
          "document_trim_length": 1200,
          "temperature": 0.2,
          "additional_prompt_instructions": [
            {
              "custom_instruction": "Prefer concise bullet point summaries when appropriate.",
              "order": 1
            }
          ]
        }
      }
    }
  }' \
  http://yoursearchcrafthost/index

Example CURL request to create an index with AI configured but disabled

Section titled “Example CURL request to create an index with AI configured but disabled”

This can be useful when an admin wants to stage AI configuration before exposing it to clients.

Terminal window
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "index": {
      "name": "product_docs_staged",
      "search_fields": ["title", "body"],
      "fields": {
        "title": { "type": "text", "stored": true },
        "body": { "type": "text", "stored": true }
      },
      "ai_enabled": false,
      "ai": {
        "llm_provider": "ollama",
        "search_summary": {
          "model": "llama3.1"
        }
      }
    }
  }' \
  http://yoursearchcrafthost/index

Patching an existing index

Section titled “Patching an existing index”

PATCH /index/:index_name accepts top-level fields instead of a nested index object.

If you include ai in a patch request, send the full AI configuration you want the index to keep.

If you include ai_enabled in a patch request, use an admin key. Patching only the ai block continues to work with an ingest key.

If an index was created without explicitly setting ai_enabled: true, patching only the ai block configures AI but does not turn it on.

Example CURL request to disable AI without removing configuration

Section titled “Example CURL request to disable AI without removing configuration”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: admin-key-value" \
  --data '{
    "ai_enabled": false
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to enable AI after configuration is in place

Section titled “Example CURL request to enable AI after configuration is in place”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: admin-key-value" \
  --data '{
    "ai_enabled": true
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to add AI summaries with Bedrock

Section titled “Example CURL request to add AI summaries with Bedrock”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "bedrock",
      "llm_region": "us-east-1",
      "search_summary": {
        "model": "anthropic.claude-3-5-sonnet-20240620-v1:0",
        "temperature": 0.2
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to add AI summaries with Anthropic

Section titled “Example CURL request to add AI summaries with Anthropic”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "anthropic",
      "llm_api_key": "sk-ant-your-api-key",
      "search_summary": {
        "model": "claude-3-5-sonnet-latest",
        "temperature": 0.2
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to add AI summaries with Google Gemini

Section titled “Example CURL request to add AI summaries with Google Gemini”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "google",
      "llm_api_key": "gemini-api-key",
      "search_summary": {
        "model": "gemini-2.5-flash",
        "temperature": 0.2
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to add AI summaries with xAI

Section titled “Example CURL request to add AI summaries with xAI”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "xai",
      "llm_api_key": "xai-your-api-key",
      "search_summary": {
        "model": "grok-3-mini",
        "temperature": 0.2
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to add AI summaries with Mistral

Section titled “Example CURL request to add AI summaries with Mistral”
Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "mistral",
      "llm_api_key": "your-mistral-api-key",
      "search_summary": {
        "model": "mistral-small-latest",
        "temperature": 0.2
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Example CURL request to replace summary instructions and keyword rules

Section titled “Example CURL request to replace summary instructions and keyword rules”

Because PATCH replaces the existing ai block when it is present, include the entire desired ai configuration when updating prompt instructions or keyword rules.

Terminal window
curl -X PATCH \
  -H "Content-Type: application/json" \
  --data '{
    "ai": {
      "llm_provider": "bedrock",
      "llm_region": "us-east-1",
      "search_summary": {
        "model": "anthropic.claude-3-5-sonnet-20240620-v1:0",
        "role": "a helpful product documentation assistant",
        "temperature": 0.2,
        "additional_prompt_instructions": [
          {
            "custom_instruction": "Highlight editorial picks first.",
            "order": 1
          },
          {
            "custom_instruction": "Call out seasonal availability when relevant.",
            "order": 2
          }
        ],
        "keyword_rules": [
          {
            "rule_name": "nutrition",
            "detect_keywords": [
              "nutrition",
              "diet"
            ],
            "replacement_term": "healthy eating",
            "custom_instruction": "Use a wellness-focused tone.",
            "empty_state_message": "Try our healthy eating guides instead.",
            "order": 10
          }
        ]
      }
    }
  }' \
  http://yoursearchcrafthost/index/product_docs

Delete this example index

Section titled “Delete this example index”
Terminal window
curl -X DELETE -H "Content-Type: application/json" http://yoursearchcrafthost/index/creation_test/

Response from stats endpoint

Section titled “Response from stats endpoint”
{
  "status": 200,
  "data": {
    "document_count": 541
  }
}