Custom Engines and API Keys

Pelorus ships with support for many engines that cover the vast open web, as well as highly specialized engines designed for technical and research literature. But you may have other engines you want to use, such as ones we have not yet started offering, or internal company engines, a documentation site, or a specific forum or website engine. You can add many of these as Custom Engines to Pelorus so you can reach them with the same search field and search modes as everything else. In addition to custom engines, many commercial engines allow you to use an API key to access their data. Those keys are also managed in Pelorus Settings.

Adding a Custom Engine

Go to Settings > Search > Search Engines and choose Add Custom Engine. An engine needs two things:

• A name, which appears on its card and in menus.
• Its search address, with {q} where your words go. For example: https://example.com/search?q={q}.

To find the correct address for the engine, search that site once in any browser for a word you will recognize, such as blender. Copy the full address of the results page, paste it into the custom engine URL field here in Pelorus, and replace your search word with {q}. Be sure to include the brace { } characters.

Once added, a custom engine behaves like any other. It appears in the Search Using list, it has a card in All Engines, and it joins Unified Search when Pelorus can read its results page. Many sites' pages cannot be read that way. Those engines still work on their own card, and contribute nothing to the Unified list.

Shortcut. A custom engine has no shortcut until you give it one. Tap the engine and fill in its Bang field.

Has Its Own Index. Turn this on only if the engine searches its own index of the web rather than reselling another engine's results. It is off by default. When it is off, this engine finding the same page does not count as a second index agreeing, which keeps the agreement counts honest.

Deleting. Tap the engine and choose Delete Engine. Custom engines are part of Pelorus Unlimited.

Using Your Own Search API Key

Many commercial engines, such as Brave Search and Kagi, offer a search API with typically metered-pricing access. Each engine's settings screen in Pelorus has a place for your own key from that service, whenever that service is known to offer API access. Simply tap the specific engine under Settings > Search > Search Engines, paste the key under API Key, and turn on Use My API Key.

With a key on, Pelorus builds that engine's results from the API instead of reading its results page. Searches made through your key are billed by that service, not by Pelorus, and you are responsible for any and all costs to use that key.

API searches in general are more reliable for Pelorus to work with, but they usually cost money for you to operate. Without API access, Pelorus runs your search query on your behalf and loads the engine's own results page into its search card; this is the same page you would see in a browser. Pelorus then reads the results off that page to build its Unified list.

Note that in some cases we cannot foresee or control, engines may return different results by API than they do from their traditional search engine results pages. Search Again with Your Key runs the current search that way once, so you can compare the results.

There are some commercial engines that, due to policy controls or technical reasons, may not be able to feed Pelorus' Unified Search. Every engine's detail screen in settings says whether it can feed a Unified Search. And, the Engine Status page keeps the current list as well as any known technical issues we are having with it.

OpenAlex

OpenAlex is a research index that works without a key, drawing on a free daily budget shared by everyone behind one public address. On a busy network that budget can run out, and the card then says Public-access limit reached and when it resets. A free key from your own OpenAlex account gives you a budget of your own, ten times larger. Tap OpenAlex under Search Engines and paste it there.

Where Keys Live

Every key you add is stored in the device Keychain. Pelorus sends a key to the service it belongs to and nowhere else: once to confirm it works, and then with each search you make through that service. Keys are never written to a file, never included in an export, and never part of iCloud settings sync. Sync Key Across Your Devices, beside each key field, sends the key to your other devices through iCloud Keychain, encrypted end to end, when you want that. Reset Pelorus removes every key.