> For the complete documentation index, see [llms.txt](https://swarmnexus.gitbook.io/swarmnexus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://swarmnexus.gitbook.io/swarmnexus/documentation/readme/technical-documentation/the-agent-api.md).

# The Agent (API)

The Agent is the official public-facing REST API for Swarm Nexus. It provides programmatic, read-only access to the Swarm Memory for developers, third-party services, and other agents in the Torus Network. It is a lightweight and efficient Node.js application built with the Hono framework.

#### Core Responsibilities

* **Programmatic Data Access:** Exposes the data stored in the Swarm Memory through a set of stable, versioned REST endpoints.
* **Read-Only Operations:** Like the Dashboard, the Agent connects to the `swarm.db` database in **read-only mode** to guarantee data integrity.
* **API Standardization:** Provides an OpenAPI (Swagger) specification, allowing for easy discovery of its capabilities and auto-generation of client libraries.
* **Health Checks:** Includes a `/healthz` endpoint for automated monitoring to confirm the service is running and can connect to the database.

#### Technical Stack

* **Framework:** Hono (a small, fast, and modern web framework for Node.js)
* **Runtime:** Node.js
* **Service Management:** `systemd` (`swarm-agent.service`)

#### How It Works

1. **Request Handling:** Nginx receives a request with the `/agent/` path prefix (e.g., `https://swarm-nexus.xyz/agent/memory/mentions`) and reverse-proxies it to the Agent server listening on `127.0.0.1:3011`.
2. **Application Logic:** The Hono application parses the request, validates parameters, and queries the `swarm.db` database.
3. **Response:** The application formats the results as a JSON object and returns them to the client.

#### Key API Endpoints

* `GET /agent/healthz`: Returns a health status check.
* `GET /agent/openapi.yaml`: Serves the OpenAPI specification file.
* `GET /agent/memory/mentions`: Queries for ingested tweets with filters for author, ticker, date ranges, and more.
* `GET /agent/memory/tickers`: Retrieves mentions related to a specific ticker.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://swarmnexus.gitbook.io/swarmnexus/documentation/readme/technical-documentation/the-agent-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.