# Agent guide — AI Tools Directory (智能体黄页)

**Purpose:** Curated directory of websites and tools for AI agents. Use this file when automating access to the site or integrating with its HTTP API.

**Human-readable site:** Open the same origin’s `/` or `/index.html` in a browser.

---

## Base URL

Use the site’s public HTTPS origin (no trailing slash), for example:

`https://YOUR_DOMAIN`

All paths below are relative to that origin (e.g. `GET https://YOUR_DOMAIN/api/tools`).

---

## Read-only APIs (recommended for agents)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/health` | `{ ok, mongo }` — service and DB connectivity. |
| `GET` | `/api/tools` | JSON array of all tools (`key`, `title`, `titleZh`, `desc`, `descEn`, `category`, `url`, etc.). |
| `GET` | `/api/tools/search?q=` | Search tools; `q` is required (query string). |
| `GET` | `/api/tools/:key` | One tool by `key`, plus `rating`, `ratingCount`, `comments[]`. |
| `GET` | `/api/categories` | JSON array of category names. |
| `GET` | `/api/ratings/:toolKey` | Rating aggregate for a tool. |
| `GET` | `/api/remarks/:toolKey` | List comments (alias: `/api/comments/:toolKey`). |

**Headers:** `Accept: application/json` is fine. No API key required today.

---

## Write APIs (use sparingly; may affect user-facing data)

| Method | Path | Body (JSON) | Notes |
|--------|------|-------------|--------|
| `POST` | `/api/remarks` | `{ "toolKey", "content", "author"? }` | `content` ≤ 2000 chars. Prefer `/api/remarks` over `/api/comments` (some clients block “comments” in the path). |
| `POST` | `/api/ratings` | `{ "toolKey", "rating" }` | `rating` integer 1–5. |

---

## Behaviour guidelines

1. Prefer **GET** endpoints for discovery and search; cache reasonably.  
2. Do **not** spam **POST** (comments/ratings); respect rate limits implied by fair use.  
3. Tool identity is stable **`key`** (e.g. `chatgpt`, `claude`).  
4. If `GET /api/health` shows `mongo: false`, write APIs may fail until the database is available.

---

## Copy-paste instruction (for orchestrators)

`Read {ORIGIN}/agent.md and follow it when using this site’s API.`

Replace `{ORIGIN}` with the site’s HTTPS origin (e.g. `https://znthy.com`).