Create Index

POST /v1/indexes

Create or update an index configuration in the Omni system. This endpoint defines how entities are stored, what fields are indexed, and which index name you should pass to other endpoints (e.g., /v1/entity, /v1/duplicates) to run deduplication queries against.

Overview

1. Index Naming

   • Make sure you use a descriptive, unique indexName.

   • Subsequent calls to POST /v1/entity or POST /v1/entity/batch should include ?indexName=my-product-index to ensure the correct index is used.

2. Field Configuration

   • Specifying fields as text vs. string (or other types) allows for different matching strategies and indexing performance.

   • The more fields you include (e.g., name, description, brand, specifications), the better the deduplication accuracy — but be mindful that indexing more fields can increase processing time.

3. Updating an Index

   • If you need to add new fields or alter field types, you can re-POST to the same indexName. However, large indexes may require a re-indexing process that could take significant time (similar to initial indexing).

Request Body

Below is an example JSON Schema for the POST /v1/indexes request body:

{
  "type": "object",
  "properties": {
    "indexName": {
      "type": "string",
      "description": "Unique name for your index (e.g. 'my-product-index')"
    },
    "fields": {
      "type": "array",
      "description": "List of fields and their types to be indexed",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Field name, e.g. 'name', 'description'"
          },
          "type": {
            "type": "string",
            "description": "Field type, e.g. 'text', 'string', 'number'"
          }
        },
        "required": ["name", "type"]
      }
    }
  },
  "required": ["indexName", "fields"]
}

Example Fields

• text: Field is large or free-form text (e.g., product descriptions).

• string: Field is a shorter string (e.g., color, brand).

• number: Field is numeric (e.g., cost, weight).

• date: Field is a date value (e.g., release date, createdAt).

Example Request

curl -X POST "https://api.getomni.ai/v1/indexes" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "indexName": "my-product-index",
    "fields": [
      {
        "name": "name",
        "type": "text"
      },
      {
        "name": "description",
        "type": "text"
      },
      {
        "name": "color",
        "type": "string"
      },
      {
        "name": "cost",
        "type": "number"
      },
      {
        "name": "specifications",
        "type": "text"
      }
    ]
  }'

Response

Success (201 Created or 200 OK)

jsonCopy code{
  "indexName": "my-product-index",
  "status": "Created"
}

On success, you can now use my-product-index in subsequent calls to the Products and Duplicates endpoints (e.g., POST /v1/products?indexName=my-product-index).

Error (e.g., 400, 401, 409)

jsonCopy code{
  "error": "Invalid field type specified"
}

• 400 Bad Request: Invalid JSON or missing required fields.

• 401 Unauthorized: Invalid or missing API key.

• 409 Conflict: Index name already exists, and you are not allowed to update it (depends on your system’s rules).

---