Indexing Documents

Once your schema is defined, you can index, retrieve, update, and delete individual documents. Each document represents a single searchable record such as a product, article, or listing.

Authentication

Operation	Header
Read (GET)	x-storeid + x-storesecret
Write (POST, DELETE)	x-storeid + x-store-write-secret

Index a Document

curl -X POST "https://api.seekora.ai/api/v1/stores/{id}/documents" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "id": "prod_1001",
    "data": {
      "title": "Wireless Noise-Cancelling Headphones",
      "description": "Premium over-ear headphones with active noise cancellation and 30-hour battery life.",
      "price": 249.99,
      "sale_price": 199.99,
      "category": "Electronics",
      "brand": "AudioPro",
      "tags": ["wireless", "noise-cancelling", "bluetooth"],
      "color": ["black", "silver"],
      "in_stock": true,
      "rating": 4.7,
      "image_url": "https://cdn.example.com/products/headphones-1001.jpg"
    },
    "action": "upsert"
  }'

Example Response

{
  "id": "prod_1001",
  "status": "created",
  "message": "Document indexed successfully"
}

Request Body

Field	Type	Required	Description
id	string	No	Unique document identifier. Auto-generated if omitted.
data	object	Yes	The document fields. Must match your schema definition.
action	string	No	Indexing action. Defaults to upsert.

Actions

Action	Behavior
upsert	Insert the document if it does not exist, or replace it entirely if it does. This is the default.
insert	Insert the document only if no document with the same ID exists. Fails if the ID is already taken.
update	Update an existing document. Fails if the document does not exist.

Retrieve a Document

curl -X GET "https://api.seekora.ai/api/v1/stores/{id}/documents/prod_1001" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

Example Response

{
  "id": "prod_1001",
  "data": {
    "title": "Wireless Noise-Cancelling Headphones",
    "description": "Premium over-ear headphones with active noise cancellation and 30-hour battery life.",
    "price": 249.99,
    "sale_price": 199.99,
    "category": "Electronics",
    "brand": "AudioPro",
    "tags": ["wireless", "noise-cancelling", "bluetooth"],
    "color": ["black", "silver"],
    "in_stock": true,
    "rating": 4.7,
    "image_url": "https://cdn.example.com/products/headphones-1001.jpg"
  }
}

Delete a Document

curl -X DELETE "https://api.seekora.ai/api/v1/stores/{id}/documents/prod_1001" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret"

Example Response

{
  "id": "prod_1001",
  "status": "deleted",
  "message": "Document deleted successfully"
}

Clear All Documents

Remove every document from your store's index. The schema is preserved.

curl -X DELETE "https://api.seekora.ai/api/v1/stores/{id}/documents" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret"

Example Response

{
  "status": "cleared",
  "message": "All documents have been removed",
  "documents_deleted": 12847
}

danger

This operation is irreversible. All documents in the index will be permanently deleted. The schema remains intact, so you can re-index without redefining your fields.

Best Practices

• Always provide an id. While the API can auto-generate IDs, using your own (such as a product SKU or database primary key) makes updates and deletes straightforward.
• Use upsert for syncing. When keeping your search index in sync with a primary database, upsert is the safest action since it handles both new and existing records.
• Validate against your schema. Documents with fields not defined in your schema, or with values that do not match the expected type, will be rejected. Retrieve your schema first if you are unsure of the current field definitions.
• Prefer bulk indexing for large datasets. For indexing more than a handful of documents at once, use the bulk indexing endpoint instead of making individual requests.