# Hermes

> Give Hermes Agent live web search, agentic search, news, page retrieval, sitemap discovery, and trending topics with the native hermes-search1api plugin.

Canonical URL: https://s1.dev/docs/integrations/hermes

`hermes-search1api` is a native [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin that gives Hermes live web access through Search1API — web search, agentic search, news search, readable page retrieval, sitemap discovery, and trending topics.

It registers these as **first-class Hermes tools** (`search1api_*`), not as a swap-in for Hermes's built-in `web_search` backend and not as an MCP bridge.

The plugin is listed in the [official Hermes plugin catalog](https://hermes-agent.nousresearch.com/docs/plugins/search1api) ([NousResearch/hermes-agent#115529](https://github.com/NousResearch/hermes-agent/pull/115529)). Hermes Agent v0.21.4 (v2026.9.21) is the first release that ships the entry; v0.21.2 (v2026.9.11) and later also read the catalog live, so they can install it by name without upgrading.

> **info:** A bundled skill (`plugin:search1api`) teaches the agent when to search, when to read a URL, and which filters fit a quick lookup versus deep research. Load it with `skill_view("plugin:search1api")`.

## Install

```bash
hermes plugins install search1api --enable
export SEARCH1API_KEY="your-key"
```

Installing by catalog name checks out the exact commit Nous reviewed (currently 0.1.0 at `14c86174`). To pick up a newer reviewed pin later, run `hermes plugins update search1api`.

`hermes plugins install superagents-lab/hermes-search1api` still works, but Hermes treats it as a custom, unreviewed source and installs the repository's latest commit.

`SEARCH1API_API_KEY` is also accepted. Put the key in `~/.hermes/.env` or the shell environment.

The official [`search1api` Python SDK](https://pypi.org/project/search1api/) is vendored into the plugin. Its only runtime dependency (`httpx`) is already part of Hermes.

## What the agent can do

| Tool | What it does |
| --- | --- |
| `search1api_search` | Live web search, with `time_range`, `include_sites` / `exclude_sites`, `search_service`, and optional `crawl_results` |
| `search1api_ask` | Agentic search with only `query` (five credits, 45-second timeout) |
| `search1api_news` | News search with the same filters |
| `search1api_crawl` | Read one public URL as clean Markdown |
| `search1api_sitemap` | Enumerate a site's URLs |
| `search1api_trending` | Trending GitHub repos or Hacker News stories |

All tools return JSON. Errors come back as `{"success": false, "error": {"type", "message", "status_code?"}}`.

## Credentials

1. Create a key in the [Search1API dashboard](https://app.s1.dev).
2. Export it as `SEARCH1API_KEY` (or `SEARCH1API_API_KEY`).

`search1api_ask` accepts only `query` (1-500 characters). Its response preserves
`query`, `intent`, result `source` and `relevance`, and optional `errors`.
See [Ask](https://s1.dev/docs/basic/ask).

## Credits

Search and news requests cost one credit each; crawling a page costs one additional credit per successfully crawled page. Agentic search costs five credits per request. New accounts receive 100 credits without a credit card. See [Credits and limits](https://s1.dev/docs/essentials/credits-and-limits) for current rates.

## Search filters and result fields

Version **0.2.0** supports all 19 [search engines](https://s1.dev/docs/basic/search) and all six
[news sources](https://s1.dev/docs/basic/news), including Bing China, Yandex, Grokipedia, and Reuters.
`time_range` supports `day`, `week`, `month`, and `year`; `page` supports search
pagination. These filters apply to search/news; agentic search accepts only `query`.

Engine-specific result fields live in optional `metadata`: GitHub search exposes
`metadata.kind`, `metadata.stars`, `metadata.language`, and `metadata.num_comments`;
Hacker News search exposes `metadata.story_url`, `metadata.points`, and
`metadata.num_comments`. Optional `published_date` stays at the result top level.
The response-level `searchParameters` describes the executed request. These paths
apply to search/news; [trending](https://s1.dev/docs/advanced/trending) keeps its separate response shape.

## Source

[github.com/superagents-lab/hermes-search1api](https://github.com/superagents-lab/hermes-search1api)