---
title: "Create Index"
method: POST
path: "/api/v1/index"
tags: ["Index"]
---

# Create Index

`POST /api/v1/index`

Create an index within the directory associated with the specified API key and return the index_id.

## Headers

- `apikey` string, required

## Request body

- CreateIndexRequest — Create index request object
  - `index_name` string, required — Index name, used for informational purposes only.
  - `schema` SchemaField[], required — Schema definition for the index: field name, field type, and indexing options. The schema defines how documents are indexed and searched. It specifies the fields that are indexed, stored, and used for faceting, as well as the field types and their properties. It also defines whether lexical, hybrid, or vector search is enabled for each field.
    - `field` string, required — unique name of a field
    - `store` boolean, required — only stored fields are returned in the search results
    - `index_lexical` boolean, required — only indexed fields can be searched
    - `index_vector` boolean — only indexed fields can be searched
    - `field_type` 'U8' | 'U16' | 'U32' | 'U64' | 'I8' | 'I16' | 'I32' | 'I64' | 'Timestamp' | 'F32' | 'F64' | 'Bool' | 'String16' | 'String32' | 'StringSet16' | 'StringSet32' | 'Point' | 'Text' | 'Json' | 'Binary', required — FieldType defines the type of a field in the document: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64, point, string, stringset, text.
    - `facet` boolean — optional faceting for a field Faceting can be enabled both for string field type and numerical field types. both numerical and string fields can be indexed (indexed=true) and stored (stored=true) in the json document, but with field_facet=true they are additionally stored in a binary format, for fast faceting and sorting without docstore access (decompression, deserialization)
    - `longest` boolean — Indicate the longest field in schema. Otherwise the longest field will be automatically detected in first index_document. Setting/detecting the longest field ensures efficient index encoding.
    - `boost` number, float — optional custom weight factor for Bm25 ranking
    - `dictionary_source` boolean — if both indexed=true and dictionary_source=true then the terms from this field are added to dictionary to the spelling correction dictionary. if disabled, then a manually generated dictionary can be used: {index_path}/dictionary.csv
    - `completion_source` boolean — if both indexed=true and completion_source=true then the n-grams (unigrams, bigrams, trigrams) from this field are added to the auto-completion list. if disabled, then a manually generated completion list can be used: {index_path}/completions.csv it is recommended to enable completion_source only for fields that contain short text with high-quality terms for auto-completion, e.g. title, author, category, product name, tags, in order to keep the extraction time and RAM requirement for completions low and the completions relevance high.
  - `similarity` 'Bm25f' | 'Bm25fProximity' — Similarity type defines the scoring and ranking of the search results: - Bm25f: considers documents composed from several fields, with different field lengths and importance - Bm25fProximity: considers term proximity, e.g. for implicit phrase search with improved relevancy
  - `tokenizer` 'AsciiAlphabetic' | 'UnicodeAlphanumeric' | 'UnicodeAlphanumericFolded' | 'Whitespace' | 'WhitespaceLowercase' | 'UnicodeAlphanumericZH' — Defines tokenizer behavior: AsciiAlphabetic - Mainly for for benchmark compatibility - Only ASCII alphabetic chars are recognized as token. UnicodeAlphanumeric - All Unicode alphanumeric chars are recognized as token. - Allows '+' '-' '#' in middle or end of a token: c++, c#, block-max. UnicodeAlphanumericFolded - All Unicode alphanumeric chars are recognized as token. - Allows '+' '-' '#' in middle or end of a token: c++, c#, block-max. - Diacritics, accents, zalgo text, umlaut, bold, italic, full-width UTF-8 characters are converted into its basic representation. - Apostroph handling prevents that short term parts preceding or following the apostroph get indexed (e.g. "s" in "someone's"). - Tokenizing might be slower due to folding and apostroph processing. UnicodeAlphanumericZH - Implements Chinese word segmentation to segment continuous Chinese text into tokens for indexing and search. - Supports mixed Latin and Chinese texts - Supports Chinese sentence boundary chars for KWIC snippets ahd highlighting. - Requires feature #[cfg(feature = "zh")]
  - `stemmer` 'None' | 'Arabic' | 'Armenian' | 'Basque' | 'Catalan' | 'Czech' | 'Danish' | 'Dutch' | 'DutchPorter' | 'English' | 'Esperanto' | 'Estonian' | 'Finnish' | 'French' | 'German' | 'Greek' | 'Hindi' | 'Hungarian' | 'Indonesian' | 'Irish' | 'Italian' | 'Lithuanian' | 'Lovins' | 'Nepali' | 'Norwegian' | 'Persian' | 'Polish' | 'Porter' | 'Portuguese' | 'Romanian' | 'Russian' | 'Serbian' | 'Sesotho' | 'Spanish' | 'Swedish' | 'Tamil' | 'Turkish' | 'Ukrainian' | 'Yiddish' — Defines stemming behavior, reducing inflected words to their word stem, base or root form. Stemming increases recall, but decreases precision. It can introduce false positive results.
  - `stop_words` union — StopwordType defines the stopword behavior: None, English, German, French, Spanish, Custom. Stopwords are removed, both from index and query: for compact index size and faster queries. Stopword removal has drawbacks: “The Who”, “Take That”, “Let it be”, “To be or not to be”, "The The", "End of days", "What might have been" are all valid queries for bands, songs, movies, literature, but become impossible when stopwords are removed. The lists of stop_words and frequent_words should not overlap.
    - 'None' — No stopwords
    - 'English' — English stopwords
    - 'German' — German stopwords
    - 'French' — French stopwords
    - 'Spanish' — Spanish stopwords
    - object — Custom stopwords
      - `Custom` object, required — Custom stopwords
        - `terms` string[], required — List of stopwords.
  - `frequent_words` union — FrequentwordType defines the frequentword behavior: None, English, German, French, Spanish, Custom. Adjacent frequent terms are combined to bi-grams, both in index and query: for shorter posting lists and faster phrase queries (only for bi-grams of frequent terms). The lists of stop_words and frequent_words should not overlap.
    - 'None' — No frequent words
    - 'English' — English frequent words
    - 'German' — German frequent words
    - 'French' — French frequent words
    - 'Spanish' — Spanish frequent words
    - object — Custom frequent words
      - `Custom` object, required — Custom frequent words
        - `terms` string[], required — List of frequent terms, max. 256 terms.
  - `ngram_indexing` integer — Specify n-gram indexing for the index. N-gram indexing can improve search performance for certain types of queries. The n-gram set is defined as a bitwise combination of the following values: - NgramSet::SingleTerm = 0b00000000,, - NgramSet::NgramFF = 0b00000001, (Ngram frequent frequent) - NgramSet::NgramFR = 0b00000010, (Ngram frequent rare) - NgramSet::NgramRF = 0b00000011, (Ngram rare frequent) - NgramSet::NgramFFF = 0b00000100, (Ngram frequent frequent frequent) - NgramSet::NgramRFF = 0b00000101, (Ngram rare frequent frequent) - NgramSet::NgramFFR = 0b00000110, (Ngram frequent frequent rare) - NgramSet::NgramFRF = 0b00000111, (Ngram frequent rare frequent) For example, to enable both NgramFF and NgramFFF, set ngram_indexing to 5 (1 | 4). Note: enabling n-gram indexing (ngram_indexing>0) will increase index size and indexing time, but improves search performance of phrase queries with frequent terms.
  - `document_compression` 'None' | 'Lz4' | 'Snappy' | 'Zstd' — Compression type for document store
  - `synonyms` Synonym[] — Specify synonyms for the index. Synonyms are used to expand search queries with additional terms that have the same or similar meaning, improving recall and search relevance. The multiway option specifies whether the synonym relationship is multiway (if true, all terms in the synonym set are considered synonyms of each other) or one-way (if false, only the first term in the synonym set is considered the main term, and the other terms are considered synonyms of the main term).
    - `terms` string[], required — List of terms that are synonyms.
    - `multiway` boolean — Creates alternative versions of documents where in each copy a term is replaced with one of its synonyms. Doesn't impact the query latency, but does increase the index size. Multi-way synonyms (default): all terms are synonyms of each other. One-way synonyms: only the first term is a synonym of the following terms, but not vice versa. E.g. [street, avenue, road] will result in searches for street to return documents containing any of the terms street, avenue or road, but searches for avenue will only return documents containing avenue, but not documents containing street or road. Currently only single terms without spaces are supported. Synonyms are supported in result highlighting. The synonyms that were created with the synonyms parameter in create_index are stored in synonyms.json in the index directory contains Can be manually modified, but becomes effective only after restart and only for newly indexed documents.
  - `spelling_correction` SpellingCorrection — Defines spelling correction (fuzzy search) and dictionary generation settings for an index.
    - `max_dictionary_edit_distance` integer, required — The edit distance thresholds for suggestions: 1..2 recommended; higher values increase latency and memory consumption.
    - `term_length_threshold` integer[], nullable — Term length thresholds for each edit distance. None: max_dictionary_edit_distance for all terms lengths Some(\[4\]): max_dictionary_edit_distance for all terms lengths >= 4, Some(\[2,8\]): max_dictionary_edit_distance for all terms lengths >=2, max_dictionary_edit_distance +1 for all terms for lengths>=8
    - `count_threshold` integer, required — The minimum frequency count for dictionary words to be considered eligible for spelling correction. Depends on the corpus size, 1..20 recommended. If count_threshold is too high, some correct words might be missed from the dictionary and deemed misspelled, if count_threshold is too low, some misspelled words from the corpus might be considered correct and added to the dictionary. Dictionary terms eligible for spelling correction (frequency count >= count_threshold) consume much more RAM, than the candidates (frequency count < count_threshold), but the terms below count_threshold will be included in dictionary.csv too.
    - `max_dictionary_entries` integer, required — Limits the maximum number of dictionary entries (terms >= count_threshold) to generate during indexing, preventing excessive RAM consumption. The number of terms in dictionary.csv will be higher, because it contains also the terms < count_threshold, to become eligible in the future during incremental dictionary updates. Dictionary terms eligible for spelling correction (frequency count >= count_threshold) consume much more RAM, than the candidates (frequency count < count_threshold). ⚠️ Above this threshold no new terms are added to the dictionary, causing them to be deemed incorrect during spelling correction and possibly changed to similar terms that are in the dictionary.
  - `query_completion` QueryCompletion — Defines query completion generation for an index.
    - `max_completion_entries` integer, required — Maximum number of completions to generate during indexing disabled if == 0
  - `clustering` union — Clustering defines the clustering behavior for approximate nearest neighbor (ANN) search: None, Auto, Fixed(usize).
    - 'None' — Exhaustive vector search, no clustering/ANN.
    - 'Auto' — The number of clusters is automatically determined depending on the number of vectors per level and shard.
    - object — Set the number of clusters to a fixed value per level and shard.
      - `Fixed` integer, required — Set the number of clusters to a fixed value per level and shard.
  - `inference` union — Inference type, to transform input text into vector embeddings. This can be a predefined model2vec model, a custom model2vec model, an external inference, or no inference.
    - object — Predefined model2vec models, already normalized + dot product = cosine similarity, use the same similarity metric that was used during the training of the embedding model.
      - `Model2Vec` object, required — Predefined model2vec models, already normalized + dot product = cosine similarity, use the same similarity metric that was used during the training of the embedding model.
        - `model` 'PotionCode16MV2' | 'PotionBase32M' | 'PotionMultilingual128M' | 'PotionRetrieval32M' | 'PotionBase8M' | 'PotionBase4M' | 'PotionBase2M', required — Predefined model type for embeddings.
        - `chunk_size` integer, required — Chunk size for splitting input text, e.g. 1000 characters. This should be the same chunk size that was used during the training of the embedding model.
        - `quantization` 'ScalarQuantizationI8' | 'TurboQuantI8' | 'None', required — Quantization method for embeddings.
    - object — Custom model2vec models, already normalized + dot product = cosine similarity, use the same similarity metric that was used during the training of the embedding model.
      - `Model2VecCustom` object, required — Custom model2vec models, already normalized + dot product = cosine similarity, use the same similarity metric that was used during the training of the embedding model.
        - `path` string, required — Model ID from Hugging Face or local path to model directory, e.g. "minishlab/potion-base-2M"
        - `chunk_size` integer, required — Chunk size for splitting input text, e.g. 1000 characters. This should be the same chunk size that was used during the training of the embedding model.
        - `quantization` 'ScalarQuantizationI8' | 'TurboQuantI8' | 'None', required — Quantization method for embeddings.
    - object — External inference
      - `External` object, required — External inference
        - `dimensions` integer, required — Number of dimensions for the embeddings.
        - `precision` 'None' | 'F32' | 'I8', required — Vector precision
        - `quantization` 'ScalarQuantizationI8' | 'TurboQuantI8' | 'None', required — Quantization method for embeddings.
        - `similarity` 'Cosine' | 'Dot' | 'Euclidean', required — Similarity measure for comparing vector embeddings.
    - 'None' — No inference

## Response `200`

Index created, returns the index_id

## Other responses

- `400` — Request object incorrect
- `401` — API key does not exists
- `404` — API key does not exists

---

[API](https://skmtc.net/seekstorm/apis/seekstorm-rest-api-documentation.md) · [All operations](https://skmtc.net/seekstorm/apis/seekstorm-rest-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/seekstorm/seekstorm-rest-api-documentation/revisions/3f780b23028a/schema)