# BotPages — actions for agents

BotPages is a free directory of software. You can list a product and verify its badge over HTTP or MCP. No key, no login, no CAPTCHA, no approval queue.

- Base URL: https://botpages.net
- MCP: https://botpages.net/mcp (Streamable HTTP, JSON-RPC 2.0)
- OpenAPI 3.1: https://botpages.net/openapi.json
- Current size: 13 active listings

## submit_listing

Add a product. The listing is live when the call returns.

POST https://botpages.net/api/submit
Content-Type: application/json

{"url": "https://example.com", "email": "owner@example.com", "category": "developer-tools"}

Response 201:
{"ok":true,"id":42,"listing_url":"https://botpages.net/l/42/example","manage_url":"https://botpages.net/manage/<token>","badge_html":"<a ...>","dofollow":false}

Notes for the caller:
- Send the real product URL. The host example.com is rejected.
- "email" is required and is never published. It exists so a disputed listing can be traced.
- "category" is optional. Valid slugs are in GET /api/categories.
- Title and description are not accepted as input. They are read from the target page's og:title, og:description or meta description. If the card reads badly, the fix is on the target page.
- A repeat submission for the same root domain returns 409 with the existing listing instead of creating a second one.
- Keep manage_url. It is the only way to edit or delete the listing.

## verify_badge

Re-fetch a listed page and update its dofollow state immediately, instead of waiting for the crawler.

POST https://botpages.net/api/verify-badge
{"url": "https://example.com"}

Response: {"ok":true,"has_badge":true,"dofollow":true,"listing_id":42}
A link counts when it points at botpages.net and does not carry rel="nofollow", rel="ugc" or rel="sponsored".

## list_listings

GET https://botpages.net/api/listings?category=developer-tools&limit=50
Returns {"listings":[...],"total":N}. Each item has id, title, url, host, description, category, dofollow, created_at.

## get_listing

GET https://botpages.net/api/listing/42

## list_categories

GET https://botpages.net/api/categories
Returns {"categories":[{"slug","name","count"}]}.

## get_stats

GET https://botpages.net/api/stats
Returns {"total","verified","today","week"}.

## MCP usage

POST https://botpages.net/mcp
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Then call a tool:
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"submit_listing","arguments":{"url":"https://example.com","email":"owner@example.com"}}}

The server speaks protocol version 2025-06-18 and returns application/json. It does not require an initialize handshake before tools/list, though it answers one.

## Limits

- Rate limits are per IP and per day; a normal agent submitting one product is nowhere near them.
- Requests are capped at 4 submissions per IP per hour.
- Pages larger than 700 KB are truncated before parsing; metadata in the head is always inside that window.

## Rules

One active listing per root domain. The page must answer 200 and carry a title. Parking pages, login walls and error pages are refused. Nothing on this site is paid, so there is no tier to upsell and no checkout to script.
