KosmoKrator

search

Algolia Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Algolia KosmoKrator integration.

10 functions 5 read 5 write API key auth
Submit Algolia feedback View package source

Lua Namespace

Agents call this integration through app.integrations.algolia.*. Use lua_read_doc("integrations.algolia") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Algolia — Lua API Reference

Search an Algolia index with full-text search, filters, and pagination.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index to search
querystringyesThe search query string. Use "" to retrieve all records
filtersstringnoFilter expression (e.g., "category:electronics AND price<100")
hitsPerPageintegernoResults per page (default: 20, max: 1000)
pageintegernoPage number, 0-based (default: 0)
attributesToRetrievearraynoAttributes to include in results
facetsarraynoFacet attributes to compute
facetFiltersarraynoFilter by facet values
numericFiltersarraynoNumeric filters (e.g., {"price>50", "price<200"})

Examples

local result = app.integrations.algolia.search({
  indexName = "products",
  query = "wireless headphones",
  hitsPerPage = 10
})

for _, hit in ipairs(result.hits) do
  print(hit.objectID .. ": " .. hit.name)
end
-- Filtered search
local result = app.integrations.algolia.search({
  indexName = "products",
  query = "",
  filters = "category:electronics AND price<100",
  hitsPerPage = 50
})

get_object

Retrieve a single record by its objectID.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index
objectIDstringyesThe unique identifier of the record
attributesToRetrievearraynoAttributes to include in the response

Example

local result = app.integrations.algolia.get_object({
  indexName = "products",
  objectID = "prod-123"
})
print(result.name)

save_object

Create or replace a record in an index.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index
objectIDstringyesThe unique identifier for the record
bodyobjectyesThe complete record data

Example

local result = app.integrations.algolia.save_object({
  indexName = "products",
  objectID = "prod-123",
  body = {
    name = "Wireless Headphones",
    price = 79.99,
    category = "electronics"
  }
})

delete_object

Delete a record from an index.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index
objectIDstringyesThe unique identifier of the record

Example

local result = app.integrations.algolia.delete_object({
  indexName = "products",
  objectID = "prod-123"
})

partial_update

Update specific attributes without replacing the entire object.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index
objectIDstringyesThe unique identifier of the record
attributesobjectyesKey-value pairs to update

Example

local result = app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    price = 89.99,
    inStock = true
  }
})

Atomic Operations

Use special _operation values for atomic updates:

-- Increment a numeric field
local result = app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    viewCount = { _operation = "Increment", value = 1 }
  }
})

list_indices

List all indices in the Algolia application.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (0-based)
hitsPerPageintegernoIndices per page (default: 100)

Example

local result = app.integrations.algolia.list_indices({})
for _, idx in ipairs(result.indices) do
  print(idx.name .. " (" .. idx.entries .. " records)")
end

get_settings

Get the configuration settings of an index.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index

Example

local result = app.integrations.algolia.get_settings({
  indexName = "products"
})
-- result contains searchableAttributes, ranking, customRanking, etc.

clear_index

Remove all records from an index (settings are preserved).

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index to clear

Example

local result = app.integrations.algolia.clear_index({
  indexName = "products"
})

batch

Perform multiple write operations in a single request.

Parameters

NameTypeRequiredDescription
indexNamestringyesThe name of the index
requestsarrayyesArray of {action, body} operations

Actions

  • addObject — Add a new record (objectID auto-generated if not provided)
  • updateObject — Update a record (body must include objectID)
  • partialUpdateObject — Partial update (body must include objectID)
  • deleteObject — Delete a record (body must include objectID)

Example

local result = app.integrations.algolia.batch({
  indexName = "products",
  requests = {
    { action = "addObject", body = { name = "New Product", price = 29.99 } },
    { action = "updateObject", body = { objectID = "prod-1", name = "Updated Name" } },
    { action = "deleteObject", body = { objectID = "prod-2" } }
  }
})
print("Processed " .. result.operationCount .. " operations")

get_current_user

List API keys to verify authentication.

Parameters

None.

Example

local result = app.integrations.algolia.get_current_user({})
print("Connected to app: " .. result.applicationId)
print("Found " .. result.keyCount .. " API keys")

Multi-Account Usage

If you have multiple Algolia accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.algolia.search({...})

-- Explicit default (portable across setups)
app.integrations.algolia.default.search({...})

-- Named accounts
app.integrations.algolia.production.search({...})
app.integrations.algolia.staging.search({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Algolia — Lua API Reference

## search

Search an Algolia index with full-text search, filters, and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index to search |
| `query` | string | yes | The search query string. Use `""` to retrieve all records |
| `filters` | string | no | Filter expression (e.g., `"category:electronics AND price<100"`) |
| `hitsPerPage` | integer | no | Results per page (default: 20, max: 1000) |
| `page` | integer | no | Page number, 0-based (default: 0) |
| `attributesToRetrieve` | array | no | Attributes to include in results |
| `facets` | array | no | Facet attributes to compute |
| `facetFilters` | array | no | Filter by facet values |
| `numericFilters` | array | no | Numeric filters (e.g., `{"price>50", "price<200"}`) |

### Examples

```lua
local result = app.integrations.algolia.search({
  indexName = "products",
  query = "wireless headphones",
  hitsPerPage = 10
})

for _, hit in ipairs(result.hits) do
  print(hit.objectID .. ": " .. hit.name)
end
```

```lua
-- Filtered search
local result = app.integrations.algolia.search({
  indexName = "products",
  query = "",
  filters = "category:electronics AND price<100",
  hitsPerPage = 50
})
```

---

## get_object

Retrieve a single record by its objectID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |
| `objectID` | string | yes | The unique identifier of the record |
| `attributesToRetrieve` | array | no | Attributes to include in the response |

### Example

```lua
local result = app.integrations.algolia.get_object({
  indexName = "products",
  objectID = "prod-123"
})
print(result.name)
```

---

## save_object

Create or replace a record in an index.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |
| `objectID` | string | yes | The unique identifier for the record |
| `body` | object | yes | The complete record data |

### Example

```lua
local result = app.integrations.algolia.save_object({
  indexName = "products",
  objectID = "prod-123",
  body = {
    name = "Wireless Headphones",
    price = 79.99,
    category = "electronics"
  }
})
```

---

## delete_object

Delete a record from an index.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |
| `objectID` | string | yes | The unique identifier of the record |

### Example

```lua
local result = app.integrations.algolia.delete_object({
  indexName = "products",
  objectID = "prod-123"
})
```

---

## partial_update

Update specific attributes without replacing the entire object.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |
| `objectID` | string | yes | The unique identifier of the record |
| `attributes` | object | yes | Key-value pairs to update |

### Example

```lua
local result = app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    price = 89.99,
    inStock = true
  }
})
```

### Atomic Operations

Use special `_operation` values for atomic updates:

```lua
-- Increment a numeric field
local result = app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    viewCount = { _operation = "Increment", value = 1 }
  }
})
```

---

## list_indices

List all indices in the Algolia application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (0-based) |
| `hitsPerPage` | integer | no | Indices per page (default: 100) |

### Example

```lua
local result = app.integrations.algolia.list_indices({})
for _, idx in ipairs(result.indices) do
  print(idx.name .. " (" .. idx.entries .. " records)")
end
```

---

## get_settings

Get the configuration settings of an index.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |

### Example

```lua
local result = app.integrations.algolia.get_settings({
  indexName = "products"
})
-- result contains searchableAttributes, ranking, customRanking, etc.
```

---

## clear_index

Remove all records from an index (settings are preserved).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index to clear |

### Example

```lua
local result = app.integrations.algolia.clear_index({
  indexName = "products"
})
```

---

## batch

Perform multiple write operations in a single request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `indexName` | string | yes | The name of the index |
| `requests` | array | yes | Array of `{action, body}` operations |

### Actions

- `addObject` — Add a new record (objectID auto-generated if not provided)
- `updateObject` — Update a record (body must include objectID)
- `partialUpdateObject` — Partial update (body must include objectID)
- `deleteObject` — Delete a record (body must include objectID)

### Example

```lua
local result = app.integrations.algolia.batch({
  indexName = "products",
  requests = {
    { action = "addObject", body = { name = "New Product", price = 29.99 } },
    { action = "updateObject", body = { objectID = "prod-1", name = "Updated Name" } },
    { action = "deleteObject", body = { objectID = "prod-2" } }
  }
})
print("Processed " .. result.operationCount .. " operations")
```

---

## get_current_user

List API keys to verify authentication.

### Parameters

None.

### Example

```lua
local result = app.integrations.algolia.get_current_user({})
print("Connected to app: " .. result.applicationId)
print("Found " .. result.keyCount .. " API keys")
```

---

## Multi-Account Usage

If you have multiple Algolia accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.algolia.search({...})

-- Explicit default (portable across setups)
app.integrations.algolia.default.search({...})

-- Named accounts
app.integrations.algolia.production.search({...})
app.integrations.algolia.staging.search({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.algolia.algolia_search({
  indexName = "example_indexName",
  query = "example_query",
  filters = "example_filters",
  hitsPerPage = 1,
  page = 1,
  attributesToRetrieve = "example_attributesToRetrieve",
  facets = "example_facets",
  facetFilters = "example_facetFilters"
})
print(result)

Functions

algolia_get_object

Retrieve a single record from an Algolia index by its objectID. Returns all attributes of the object.

Operation
Read read
Full name
algolia.algolia_get_object
ParameterTypeRequiredDescription
indexName string yes The name of the index.
objectID string yes The unique identifier of the record.
attributesToRetrieve array no List of attributes to include in the response. Default: all attributes.

algolia_save_object

Create or replace a record in an Algolia index. The object is identified by its objectID. If a record with this objectID exists, it will be fully replaced.

Operation
Write write
Full name
algolia.algolia_save_object
ParameterTypeRequiredDescription
indexName string yes The name of the index.
objectID string yes The unique identifier for the record.
body object yes The complete record data. Must include all attributes you want stored. The objectID will be set automatically.

algolia_delete_object

Delete a record from an Algolia index by its objectID. This action is irreversible.

Operation
Write write
Full name
algolia.algolia_delete_object
ParameterTypeRequiredDescription
indexName string yes The name of the index.
objectID string yes The unique identifier of the record to delete.

algolia_partial_update

Update specific attributes of a record without replacing the entire object. Only the specified attributes will be changed; all other attributes remain unchanged.

Operation
Write write
Full name
algolia.algolia_partial_update
ParameterTypeRequiredDescription
indexName string yes The name of the index.
objectID string yes The unique identifier of the record to update.
attributes object yes Key-value pairs of attributes to update. Only the specified attributes will be changed. Use special operations like {"_operation":"Increment","value":1} for atomic updates.

algolia_list_indices

List all indices in the Algolia application. Returns index names, entry counts, and sizes information.

Operation
Read read
Full name
algolia.algolia_list_indices
ParameterTypeRequiredDescription
page integer no Page number for pagination (0-based). Default: 0.
hitsPerPage integer no Number of indices per page. Default: 100.

algolia_get_settings

Get the configuration settings of an Algolia index, including searchable attributes, ranking, facets, and more.

Operation
Read read
Full name
algolia.algolia_get_settings
ParameterTypeRequiredDescription
indexName string yes The name of the index.

algolia_clear_index

Remove all records from an Algolia index. The index itself is preserved with its settings. This action is irreversible.

Operation
Write write
Full name
algolia.algolia_clear_index
ParameterTypeRequiredDescription
indexName string yes The name of the index to clear.

algolia_batch

Perform multiple write operations (addObject, updateObject, partialUpdateObject, deleteObject) in a single batch request for better performance.

Operation
Write write
Full name
algolia.algolia_batch
ParameterTypeRequiredDescription
indexName string yes The name of the index.
requests array yes Array of batch operations. Each request must have "action" (addObject, updateObject, partialUpdateObject, deleteObject) and "body" (the record data). For update/delete, body must include "objectID".

algolia_get_current_user

List API keys for the Algolia application. Use this to verify that authentication is working and to see which API keys exist.

Operation
Read read
Full name
algolia.algolia_get_current_user
ParameterTypeRequiredDescription
No parameters.