Skip to main content

Algolia

Search, index and configure your Algolia indices from agent sessions.

Connect it with: API key. Algolia's own documentation: https://www.algolia.com/doc/rest-api/search/.

What agents can do​

Connect Algolia so the agents working your tasks can reach it. With it connected, they can:

  • Search any index of your application, with filters, facets and ranking, to answer questions or check content.
  • Add, update and delete records when a task changes the data behind your search.
  • Read and change index settings (searchable attributes, ranking, synonyms, rules) and copy or clear an index.
  • List the indices in the application to see what exists before changing anything.

Before you start​

  • An Algolia account with at least one application (the free Build plan is enough).
  • Access to the application's Settings > API Keys page, which needs the Owner or an Admin role in Algolia's team settings to see the Write API Key.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Algolia​

Jaah connects to Algolia with an API key, not with a sign-in button.

Connect with an API key​

Find each value first:

  • Application ID: In the Algolia dashboard open Settings > API Keys (dashboard.algolia.com/account/api-keys); the Application ID is the first value at the top of the page.
  • API key: On the same Settings > API Keys page, copy the Write API Key, or under All API Keys select New API Key and grant it at least the listIndexes ACL plus the ACLs your agents need (search, addObject, editSettings). The Search-Only API Key cannot pass the Test.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Algolia card.
  2. Name the secret and choose who can use it.
  3. Fill in Application ID, API key.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to Algolia with an API key, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah calls Algolia's API once (GET https://<Application ID>.algolia.net/1/indexes?page=0&hitsPerPage=1) with the stored values, and shows whether Algolia accepted it, or which value Algolia refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: app_id, api_key.

Tell the agent in your task description which secret to use, for example “use the Algolia secret org/algolia”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Algolia once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Algolia's side too, revoke or delete the key at Algolia.

Limitations​

  • The Test lists the application's indices, so the key needs the listIndexes ACL: a Search-Only API Key is refused with 403.
  • A secured API key (one your backend derives from another key) is not supported: connect the parent key instead.
  • Algolia meters search and indexing operations, so heavy agent use counts against your plan's monthly records and requests.
  • Agents can do only what the connected Algolia account allows.

Troubleshooting​

The Test says Algolia rejected the API key (403)

Either the Application ID and key belong to different applications, or the key lacks the listIndexes ACL. Copy both values again from the same Settings > API Keys page, or edit the key under All API Keys and add listIndexes.

The Test says Algolia cannot be reached at that address

The Application ID is mistyped: it is 10 letters and digits, with no spaces and no https:// prefix. Copy it again from Settings > API Keys.

Agents can search but writes fail with 403

The key is restricted to read ACLs or to some indices. Use the Write API Key, or edit the key's ACLs and Indices restriction under All API Keys.

Still stuck? Select Test and read the result: it names the value Algolia refused and the status it answered.

FAQ​

Which Algolia key should I use?

The Write API Key works for everything. For least privilege, create a key under All API Keys with listIndexes, search and only the write ACLs your agents need, restricted to the indices they should touch.

Can I use the Admin API Key?

Yes, but it can also manage other keys and delete any index. Prefer the Write API Key or a dedicated key.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Algolia account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.