Bulk Indexing

The bulk indexing endpoint lets you index, update, or delete multiple documents in a single request. This is significantly faster than making individual requests when working with large datasets.

Authentication

Header	Description
x-storeid	Your store identifier
x-store-write-secret	Write API secret

Bulk Index Documents

curl -X POST "https://api.seekora.ai/api/v1/stores/{id}/documents/bulk" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "documents": [
      {
        "id": "prod_2001",
        "action": "upsert",
        "data": {
          "title": "Organic Cotton T-Shirt",
          "price": 34.00,
          "category": "Apparel",
          "brand": "EcoWear",
          "color": ["white", "navy"],
          "size": ["S", "M", "L", "XL"],
          "in_stock": true,
          "rating": 4.3,
          "image_url": "https://cdn.example.com/products/tshirt-2001.jpg"
        }
      },
      {
        "id": "prod_2002",
        "action": "upsert",
        "data": {
          "title": "Slim Fit Chino Pants",
          "price": 68.00,
          "category": "Apparel",
          "brand": "UrbanBasics",
          "color": ["khaki", "olive", "black"],
          "size": ["30", "32", "34", "36"],
          "in_stock": true,
          "rating": 4.5,
          "image_url": "https://cdn.example.com/products/chinos-2002.jpg"
        }
      },
      {
        "id": "prod_2003",
        "action": "upsert",
        "data": {
          "title": "Leather Crossbody Bag",
          "price": 120.00,
          "category": "Accessories",
          "brand": "CraftHouse",
          "color": ["brown", "tan"],
          "in_stock": false,
          "rating": 4.8,
          "image_url": "https://cdn.example.com/products/bag-2003.jpg"
        }
      }
    ]
  }'

Response Format

Bulk operations return an HTTP 207 Multi-Status response. Each document in the request receives its own status, allowing you to identify which operations succeeded and which failed.

Fully Successful Response

{
  "status": 207,
  "results": [
    { "id": "prod_2001", "status": "created", "code": 201 },
    { "id": "prod_2002", "status": "created", "code": 201 },
    { "id": "prod_2003", "status": "created", "code": 201 }
  ],
  "summary": {
    "total": 3,
    "succeeded": 3,
    "failed": 0
  }
}

Partial Success Response

When some documents fail validation or encounter errors, the response includes details for each failure while the valid documents are still indexed.

{
  "status": 207,
  "results": [
    { "id": "prod_2001", "status": "created", "code": 201 },
    {
      "id": "prod_2002",
      "status": "failed",
      "code": 400,
      "error": "Field 'price' expected type float, got string"
    },
    { "id": "prod_2003", "status": "updated", "code": 200 }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Request Structure

Each entry in the documents array follows the same format as a single document indexing request.

Field	Type	Required	Description
id	string	No	Unique document identifier. Auto-generated if omitted.
data	object	Yes	Document fields matching your schema.
action	string	No	upsert (default), insert, or update.

Best Practices

• Use batches of 100-500 documents. This balances throughput against request size limits. Very large payloads may time out or exceed memory limits.
• Always check the summary field. Even a 207 response may contain failures. Use the summary.failed count to decide whether to retry.
• Retry only failed documents. Extract the failed entries from the results array, fix any validation errors, and resubmit only those documents.
• Use upsert for full catalog syncs. When re-indexing your entire catalog, upsert ensures both new and existing products are handled correctly without needing to track which documents already exist.
• Run bulk operations during off-peak hours when possible. Large indexing jobs consume resources that may affect search query latency.