Can I use Algolia as a CLI?

Yes. KosmoKrator exposes a Algolia CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Algolia through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Algolia tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Algolia credentials stored?

Algolia credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Algolia MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

data

Algolia Lua API for KosmoKrator Agents

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

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.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Algolia workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.algolia.add_api_key({payload = "example_payload"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("algolia"))' --json
kosmo integrations:lua --eval 'print(docs.read("algolia.add_api_key"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local algolia = app.integrations.algolia
local result = algolia.add_api_key({payload = "example_payload"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.algolia, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.algolia.default.* or app.integrations.algolia.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Algolia, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

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

Namespace: app.integrations.algolia

Use Algolia tools to search indices, manage objects and index settings, maintain synonyms and query rules, inspect tasks and logs, and manage API keys. Full write coverage needs an Admin API key. Search-only keys can use search and read tools only.

Search

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

local multi = app.integrations.algolia.search_multiple({
  requests = {
    { indexName = "products", params = "query=headphones&hitsPerPage=5" },
    { indexName = "articles", params = "query=headphones&hitsPerPage=5" }
  }
})

local facets = app.integrations.algolia.search_facet_values({
  indexName = "products",
  facetName = "brand",
  params = { facetQuery = "sony" }
})

Use browse when the agent needs to export or scan an index. Continue with the returned cursor until the response has no cursor.

Objects

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

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

app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    price = 69.99
  }
})

Batch writes use Algolia batch request objects:

app.integrations.algolia.batch({
  indexName = "products",
  requests = {
    { action = "addObject", body = { objectID = "prod-1", name = "A" } },
    { action = "deleteObject", body = { objectID = "prod-2" } }
  }
})

Indices And Settings

local indices = app.integrations.algolia.list_indices({})
local settings = app.integrations.algolia.get_settings({ indexName = "products" })

app.integrations.algolia.set_settings({
  indexName = "products",
  settings = {
    searchableAttributes = { "name", "description" },
    attributesForFaceting = { "brand", "category" }
  },
  query = { forwardToReplicas = true }
})

clear_index removes records but preserves settings. delete_index removes the index. index_operation can copy or move an index to a destination index.

Synonyms

app.integrations.algolia.save_synonym({
  indexName = "products",
  objectID = "phone-mobile",
  payload = {
    objectID = "phone-mobile",
    type = "synonym",
    synonyms = { "phone", "mobile" }
  }
})

local found = app.integrations.algolia.search_synonyms({
  indexName = "products",
  params = { query = "phone" }
})

Use batch_synonyms for bulk replacement and clear_synonyms only when the agent is explicitly asked to remove all synonyms.

Rules

app.integrations.algolia.save_rule({
  indexName = "products",
  objectID = "boost-headphones",
  payload = {
    objectID = "boost-headphones",
    condition = { pattern = "headphones", anchoring = "contains" },
    consequence = {
      params = {
        filters = "category:audio"
      }
    }
  }
})

local rules = app.integrations.algolia.search_rules({
  indexName = "products",
  params = { query = "headphones" }
})

Keys, Logs, And Tasks

local keys = app.integrations.algolia.list_api_keys({})
local logs = app.integrations.algolia.list_logs({
  query = { length = 10, type = "all" }
})

local task = app.integrations.algolia.get_task({
  indexName = "products",
  taskID = "123456"
})

The legacy get_current_user slug lists API keys. New agents should use list_api_keys.

Raw API Helpers

Use api_get, api_post, api_put, and api_delete for relative paths below the Algolia /1 API root when no dedicated tool exists. Full URLs and parent-directory paths are rejected.

local response = app.integrations.algolia.api_get({
  path = "/indexes/products/settings"
})

Multi-Account

app.integrations.algolia.production.search({ indexName = "products", query = "headphones" })
app.integrations.algolia.staging.search({ indexName = "products", query = "headphones" })

Raw agent markdown

# Algolia Lua API Reference

Namespace: `app.integrations.algolia`

Use Algolia tools to search indices, manage objects and index settings, maintain synonyms and query rules, inspect tasks and logs, and manage API keys. Full write coverage needs an Admin API key. Search-only keys can use search and read tools only.

## Search

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

local multi = app.integrations.algolia.search_multiple({
  requests = {
    { indexName = "products", params = "query=headphones&hitsPerPage=5" },
    { indexName = "articles", params = "query=headphones&hitsPerPage=5" }
  }
})

local facets = app.integrations.algolia.search_facet_values({
  indexName = "products",
  facetName = "brand",
  params = { facetQuery = "sony" }
})
```

Use `browse` when the agent needs to export or scan an index. Continue with the returned cursor until the response has no cursor.

## Objects

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

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

app.integrations.algolia.partial_update({
  indexName = "products",
  objectID = "prod-123",
  attributes = {
    price = 69.99
  }
})
```

Batch writes use Algolia batch request objects:

```lua
app.integrations.algolia.batch({
  indexName = "products",
  requests = {
    { action = "addObject", body = { objectID = "prod-1", name = "A" } },
    { action = "deleteObject", body = { objectID = "prod-2" } }
  }
})
```

## Indices And Settings

```lua
local indices = app.integrations.algolia.list_indices({})
local settings = app.integrations.algolia.get_settings({ indexName = "products" })

app.integrations.algolia.set_settings({
  indexName = "products",
  settings = {
    searchableAttributes = { "name", "description" },
    attributesForFaceting = { "brand", "category" }
  },
  query = { forwardToReplicas = true }
})
```

`clear_index` removes records but preserves settings. `delete_index` removes the index. `index_operation` can copy or move an index to a destination index.

## Synonyms

```lua
app.integrations.algolia.save_synonym({
  indexName = "products",
  objectID = "phone-mobile",
  payload = {
    objectID = "phone-mobile",
    type = "synonym",
    synonyms = { "phone", "mobile" }
  }
})

local found = app.integrations.algolia.search_synonyms({
  indexName = "products",
  params = { query = "phone" }
})
```

Use `batch_synonyms` for bulk replacement and `clear_synonyms` only when the agent is explicitly asked to remove all synonyms.

## Rules

```lua
app.integrations.algolia.save_rule({
  indexName = "products",
  objectID = "boost-headphones",
  payload = {
    objectID = "boost-headphones",
    condition = { pattern = "headphones", anchoring = "contains" },
    consequence = {
      params = {
        filters = "category:audio"
      }
    }
  }
})

local rules = app.integrations.algolia.search_rules({
  indexName = "products",
  params = { query = "headphones" }
})
```

## Keys, Logs, And Tasks

```lua
local keys = app.integrations.algolia.list_api_keys({})
local logs = app.integrations.algolia.list_logs({
  query = { length = 10, type = "all" }
})

local task = app.integrations.algolia.get_task({
  indexName = "products",
  taskID = "123456"
})
```

The legacy `get_current_user` slug lists API keys. New agents should use `list_api_keys`.

## Raw API Helpers

Use `api_get`, `api_post`, `api_put`, and `api_delete` for relative paths below the Algolia `/1` API root when no dedicated tool exists. Full URLs and parent-directory paths are rejected.

```lua
local response = app.integrations.algolia.api_get({
  path = "/indexes/products/settings"
})
```

## Multi-Account

```lua
app.integrations.algolia.production.search({ indexName = "products", query = "headphones" })
app.integrations.algolia.staging.search({ indexName = "products", query = "headphones" })
```

Metadata-derived Lua example

local result = app.integrations.algolia.add_api_key({payload = "example_payload"})
print(result)

Functions

add_api_key Write

Add a restricted Algolia API key with ACLs and optional restrictions.

Lua path: app.integrations.algolia.add_api_key
Full name: algolia.algolia_add_api_key

Parameter	Type	Required	Description
`payload`	object	yes	API key payload including acl and optional restrictions.

api_delete Read

Call a safe relative Algolia API path with DELETE for endpoints not covered by a dedicated tool.

Lua path: app.integrations.algolia.api_delete
Full name: algolia.algolia_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative path below /1.
`query`	object	no	Optional query parameters.

api_get Read

Call a safe relative Algolia API path with GET for endpoints not covered by a dedicated tool.

Lua path: app.integrations.algolia.api_get
Full name: algolia.algolia_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative path below /1.
`query`	object	no	Optional query parameters.
`use_search_endpoint`	boolean	no	Use the DSN search endpoint.

api_post Read

Call a safe relative Algolia API path with POST for endpoints not covered by a dedicated tool.

Lua path: app.integrations.algolia.api_post
Full name: algolia.algolia_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative path below /1.
`payload`	object	no	JSON request body.
`query`	object	no	Optional query parameters.
`use_search_endpoint`	boolean	no	Use the DSN search endpoint.

api_put Read

Call a safe relative Algolia API path with PUT for endpoints not covered by a dedicated tool.

Lua path: app.integrations.algolia.api_put
Full name: algolia.algolia_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative path below /1.
`payload`	object	no	JSON request body.
`query`	object	no	Optional query parameters.

batch Read

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

Lua path: app.integrations.algolia.batch
Full name: algolia.algolia_batch

Parameter	Type	Required	Description
`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".

batch_rules Read

Create or update multiple Algolia query rules in one request.

Lua path: app.integrations.algolia.batch_rules
Full name: algolia.algolia_batch_rules

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`rules`	array	yes	Array of rule objects.
`query`	object	no	Optional query parameters such as clearExistingRules or forwardToReplicas.

batch_synonyms Read

Create or update multiple Algolia synonyms in one request.

Lua path: app.integrations.algolia.batch_synonyms
Full name: algolia.algolia_batch_synonyms

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`synonyms`	array	yes	Array of synonym objects.
`query`	object	no	Optional query parameters such as replaceExistingSynonyms or forwardToReplicas.

browse Read

Browse records in an Algolia index for exports or complete scans.

Lua path: app.integrations.algolia.browse
Full name: algolia.algolia_browse

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`params`	object	no	Browse parameters such as query, cursor, filters, or hitsPerPage.

clear_index Read

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

Lua path: app.integrations.algolia.clear_index
Full name: algolia.algolia_clear_index

Parameter	Type	Required	Description
`indexName`	string	yes	The name of the index to clear.

clear_rules Read

Clear query rules from an Algolia index.

Lua path: app.integrations.algolia.clear_rules
Full name: algolia.algolia_clear_rules

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`query`	object	no	Optional query parameters such as forwardToReplicas.

clear_synonyms Read

Clear synonyms from an Algolia index.

Lua path: app.integrations.algolia.clear_synonyms
Full name: algolia.algolia_clear_synonyms

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`query`	object	no	Optional query parameters such as forwardToReplicas.

delete_api_key Write

Delete an Algolia API key.

Lua path: app.integrations.algolia.delete_api_key
Full name: algolia.algolia_delete_api_key

Parameter	Type	Required	Description
`key`	string	yes	The API key value.

delete_index Write

Delete an Algolia index and all its records.

Lua path: app.integrations.algolia.delete_index
Full name: algolia.algolia_delete_index

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.

delete_object Write

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

Lua path: app.integrations.algolia.delete_object
Full name: algolia.algolia_delete_object

Parameter	Type	Required	Description
`indexName`	string	yes	The name of the index.
`objectID`	string	yes	The unique identifier of the record to delete.

delete_rule Write

Delete one Algolia query rule by objectID.

Lua path: app.integrations.algolia.delete_rule
Full name: algolia.algolia_delete_rule

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The rule objectID.

delete_synonym Write

Delete one Algolia synonym by objectID.

Lua path: app.integrations.algolia.delete_synonym
Full name: algolia.algolia_delete_synonym

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The synonym objectID.

get_api_key Read

Get settings and ACLs for one Algolia API key.

Lua path: app.integrations.algolia.get_api_key
Full name: algolia.algolia_get_api_key

Parameter	Type	Required	Description
`key`	string	yes	The API key value.

get_current_user Read

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

Lua path: app.integrations.algolia.get_current_user
Full name: algolia.algolia_get_current_user

Parameter	Type	Required	Description
No parameters.

get_object Read

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

Lua path: app.integrations.algolia.get_object
Full name: algolia.algolia_get_object

Parameter	Type	Required	Description
`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.

get_rule Read

Get one Algolia query rule by objectID.

Lua path: app.integrations.algolia.get_rule
Full name: algolia.algolia_get_rule

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The rule objectID.

get_settings Read

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

Lua path: app.integrations.algolia.get_settings
Full name: algolia.algolia_get_settings

Parameter	Type	Required	Description
`indexName`	string	yes	The name of the index.

get_synonym Read

Get one Algolia synonym by objectID.

Lua path: app.integrations.algolia.get_synonym
Full name: algolia.algolia_get_synonym

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The synonym objectID.

get_task Read

Get the status of an Algolia indexing task.

Lua path: app.integrations.algolia.get_task
Full name: algolia.algolia_get_task

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`taskID`	string	yes	The Algolia task ID.

index_operation Read

Run an Algolia index operation such as copy or move to another index.

Lua path: app.integrations.algolia.index_operation
Full name: algolia.algolia_index_operation

Parameter	Type	Required	Description
`indexName`	string	yes	Source index name.
`operation`	string	yes	Operation name, such as copy or move.
`destination`	string	yes	Destination index name.
`extra`	object	no	Optional additional operation payload.

list_api_keys Read

List Algolia API keys in the application.

Lua path: app.integrations.algolia.list_api_keys
Full name: algolia.algolia_list_api_keys

Parameter	Type	Required	Description
No parameters.

list_indices Read

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

Lua path: app.integrations.algolia.list_indices
Full name: algolia.algolia_list_indices

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (0-based). Default: 0.
`hitsPerPage`	integer	no	Number of indices per page. Default: 100.

list_logs Read

List recent Algolia logs for API activity and troubleshooting.

Lua path: app.integrations.algolia.list_logs
Full name: algolia.algolia_list_logs

Parameter	Type	Required	Description
`query`	object	no	Optional log query parameters such as offset, length, type, and indexName.

partial_update Read

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

Lua path: app.integrations.algolia.partial_update
Full name: algolia.algolia_partial_update

Parameter	Type	Required	Description
`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.

save_object Read

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.

Lua path: app.integrations.algolia.save_object
Full name: algolia.algolia_save_object

Parameter	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. Must include all attributes you want stored. The objectID will be set automatically.

save_rule Read

Create or replace an Algolia query rule.

Lua path: app.integrations.algolia.save_rule
Full name: algolia.algolia_save_rule

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The rule objectID.
`payload`	object	yes	Rule payload.

save_synonym Read

Create or replace an Algolia synonym.

Lua path: app.integrations.algolia.save_synonym
Full name: algolia.algolia_save_synonym

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`objectID`	string	yes	The synonym objectID.
`payload`	object	yes	Synonym payload.

search Read

Search an Algolia index. Supports full-text search with filters, faceting, and pagination. Use this to find records matching a query string or filter criteria.

Lua path: app.integrations.algolia.search
Full name: algolia.algolia_search

Parameter	Type	Required	Description
`indexName`	string	yes	The name of the index to search.
`query`	string	yes	The search query string. Use an empty string "" to retrieve all records (with filters).
`filters`	string	no	Filter expression (e.g., "category:electronics AND price<100").
`hitsPerPage`	integer	no	Number of results per page (default: 20, max: 1000).
`page`	integer	no	Page number (0-based). Default: 0.
`attributesToRetrieve`	array	no	List of attributes to include in results. Default: ["*"] (all).
`facets`	array	no	List of facet attributes to compute.
`facetFilters`	array	no	Filter by facet values, e.g. [["category:electronics"], ["brand:Apple"]].
`numericFilters`	array	no	Numeric filters, e.g. ["price>50", "price<200"].

search_facet_values Read

Search values for an Algolia facet attribute.

Lua path: app.integrations.algolia.search_facet_values
Full name: algolia.algolia_search_facet_values

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`facetName`	string	yes	The facet attribute name.
`params`	object	no	Facet search parameters such as facetQuery and filters.

search_multiple Read

Search multiple Algolia indices in one request using the multiple queries endpoint.

Lua path: app.integrations.algolia.search_multiple
Full name: algolia.algolia_search_multiple

Parameter	Type	Required	Description
`requests`	array	yes	Array of query objects with indexName and params.
`strategy`	string	no	Multiple query strategy. Defaults to none.

search_rules Read

Search query rules in an Algolia index.

Lua path: app.integrations.algolia.search_rules
Full name: algolia.algolia_search_rules

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`params`	object	no	Rule search parameters such as query, page, and hitsPerPage.

search_synonyms Read

Search synonyms in an Algolia index.

Lua path: app.integrations.algolia.search_synonyms
Full name: algolia.algolia_search_synonyms

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`params`	object	no	Search parameters such as query, type, page, and hitsPerPage.

set_settings Read

Update Algolia index settings such as searchableAttributes, ranking, facets, replicas, and typo tolerance.

Lua path: app.integrations.algolia.set_settings
Full name: algolia.algolia_set_settings

Parameter	Type	Required	Description
`indexName`	string	yes	The index name.
`settings`	object	yes	Settings payload.
`query`	object	no	Optional query parameters such as forwardToReplicas.

update_api_key Write

Update ACLs and restrictions for an Algolia API key.

Lua path: app.integrations.algolia.update_api_key
Full name: algolia.algolia_update_api_key

Parameter	Type	Required	Description
`key`	string	yes	The API key value.
`payload`	object	yes	Updated API key payload.