Creating a vector index programmatically

You can programmatically create a vector index asset programmatically to efficiently retrieve passages of text from documents stored in a vector data store.

You can choose from different types of vector data stores to index your grounding documents. For details about vector stores, including vectorization and search settings, supported document file types, and supported encoder models, see Vector index settings.

Before you begin

You must have the Admin or Editor role in a project.
You must generate credentials to authenticate with watsonx.ai APIs. For details, see Generating a bearer token.

Note:

You can only use the ms-marco-minilm-l-12-v2 reranker model to rerank results of a vector search when you create a vector index asset with the API.

Alternatively, you can use graphical tools from the watsonx.ai UI to create vector indexes. See Creating a vector index from the UI.

Procedure

You can use the watsonx.ai REST API to create and manage a vector index asset in your project. For details see the Vector indexes - transactional APIs in the watsonx.ai API reference documentation.

The high-level steps that you follow to create a vector index asset with the REST API are mostly the same for each type of vector data store. The key differences are the values to include in the request body for the vector index asset and are highlighted in the following procedure:

Upload your grounding documents as data assets in the project and note the asset IDs for your files.

To retreive the asset ID for your file:
1. From the Assets tab in the project, select the Data > Data assets asset type.
2. Click on the name of your grounding document file asset.
3. The ID can be retrieved from the portion of the URL after data-assets/. The URL format is as follows:
```
https://<host-name>/projects/<project-id>/data-assets/<asset-id>
```

Create a vector index asset for your vector data store. The REST API request creates the index asset and generates the text embeddings for the documents stored in the vector data store. The documents are referenced by using their data asset IDs and vector search results are reranked.

Restriction: You cannot adjust search result and reranking settings for a vector index asset created with the API.

In-memory vector store

The following sample REST API request creates a vector index asset in your project for an in-memory vector store:

curl --location --request POST 'https://<region>.<cloud-provider-domain>/v1/transactional_vector_indexes?version=2026-01-05' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "project_id": "4e34d515-c61f-4f18-92b4-758be78d0a58",
      "name": "transactional-flow-external-inmemory",
      "description": "Create vector index with API",
      "data_assets": [
          "df9ea6b4-2382-4ab7-aa54-d82e9432db34",
          "2ee31d21-f57b-4c76-b492-6cdb3c0d8389"
      ],
      "store": {
          "type": "memory"
      },
      "settings": {
          "chunk_size": 2000,
          "chunk_overlap": 200,
          "top_k": 3,
          "split_pdf_pages": true,
          "rerank": true,
          "embedding_model_id": "sentence-transformers/all-minilm-l6-v2"
      }
  }'

Elasticsearch vector store

Create a connection to the Elasticsearch vector store before you use the connection ID to create the vector index. For details, see Setting up a Elasticsearch vector store.

The following sample REST API request creates a vector index asset in your project for an Elasticsearch vector store:

curl --location --request POST 'https://<region>.<cloud-provider-domain>/v1/transactional_vector_indexes?version=2026-01-05' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
      "project_id": "4e34d515-c61f-4f18-92b4-758be78d0a58",
      "name": "transactional-flow-external-elastic",
      "description": "My first vector index",
      "data_assets": [
         "5aa17ada-fdf9-4453-82dd-cf9ea84ab569"
      ],
      "store": {
          "type": "elasticsearch",
          "connection_id": "697dbae3-13b1-4ca9-8b65-16248e2d2675",
          "index": "wx-newindex",
          "new_index": true,
          "database": "rag"
      },
      "settings": {
          "chunk_size": 2000,
          "chunk_overlap": 200,
          "top_k": 3,
          "split_pdf_pages": true,
          "rerank": true,
          "embedding_model_id": ".elser_model_2",
          "schema_fields": {
          "document_name": "metadata.document_name",
          "text": "text",
          "page_number": "metadata.page",
          "vector_query": "vector"
      }
  }'

watsonx.data Milvus vector store

Create a connection to the watsonx.data Milvus vector store before you use the connection ID to create the vector index. For details, see Setting up a watsonx.data Milvus vector store.

The following sample REST API request creates a vector index asset in your project for a watsonx.data Milvus vector store:

curl --location --request POST 'https://<region>.<cloud-provider-domain>/v1/transactional_vector_indexes?version=2026-01-05' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
      "project_id": "4e34d515-c61f-4f18-92b4-758be78d0a58",
      "name": "transactional-flow-external-milvus-may29",
      "description": "My first vector index",
      "data_assets": [
          "09dcb221-e262-4bba-9c72-18be5e5fe9e8"
      ],
      "store": {
          "type": "watsonx.data",
          "connection_id": "a02785b4-aa31-4a54-8a12-52df08c56b38",
          "index": "wx_milvusindex",
          "new_index": true,
          "database": "default"
      },
      "settings": {
          "chunk_size": 2000,
          "chunk_overlap": 200,
          "top_k": 3,
          "split_pdf_pages": true,
          "rerank": true,
          "embedding_model_id": "sentence-transformers/all-minilm-l6-v2",
          "schema_fields": {
          "document_name": "document_name",
          "text": "text",
          "page_number": "page"
      }
  }'

For external vector stores only: The REST API response returns the vector index asset ID and the Python notebook asset ID for a notebook that starts the job run to generate text embeddings in the external vector store. The response also contains the embeddings generation job ID.

You can manage the vector index asset by updating the Python notebook, vectorization settings, and data assets.

Run the following sample REST API request to edit the vectorization settings for the vector index asset:

curl --location --request POST 'https://<region>.<cloud-provider-domain>/v1/transactional_vector_indexes/<vector-index-asset-id>' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "settings": {
          "chunk_size": 2000,
          "chunk_overlap": 200,
          "top_k": 3,
          "split_pdf_pages": true,
          "rerank": false,
          "embedding_model_id": "ibm/granite-embedding-278m-multilingual",
          "schema_fields": {
              "document_name": "document_name",
              "text": "text",
              "page_number": "page"
          }
      }
  }'

What to do next

You can now experiment with retrieval-augmented generation (RAG) patterns with the vector index asset that stores your document set. Save the prompt logic in a notebook that you can use in your generative AI application. For details, see Saving your work andRetrieval-augmented generation.