$ endpoints

GET/api/v1/services

List and filter all services. Returns paginated results with full protocol details.

// parameters

- category — filter by category slug (think, browse, pay, etc.)
- has_mcp=true — only services with MCP servers
- verified_interfaces — on every service, the badges we actually fetched and confirmed; a flag that is true but absent here is claimed, not verified
- accepts_mpp=true — only services accepting MPP
- accepts_x402=true — only services accepting x402
- has_skill_file=true — only services with skill files
- has_llms_txt=true — only services with llms.txt
- auth_method — filter by auth (api-key, m2m-oauth, bot-token, wallet, x402-none, none)
- search — full-text search across name, description, tags
- min_score — minimum bot-friendly score (1-5)
- sort — score (default), votes, name, newest
- promoted — true for promoted only, false for organic only
- page, per_page — pagination (default 1, 20; max 100)

// example

curl "https://www.botfriendly.xyz/api/v1/services?category=browse&has_mcp=true"

GET/api/v1/services/{slug}

Get full details for a single service including all protocol support, URLs, and metadata.

// example

curl "https://www.botfriendly.xyz/api/v1/services/browserbase"

GET/api/v1/search

Full-text search across services. Returns results ranked by bot_score.

// parameters

- q (required) — search query (supports websearch syntax)
- category — filter by category slug
- page, per_page — pagination (default 1, 20; max 100)

// example

curl "https://www.botfriendly.xyz/api/v1/search?q=vector+database"

GET/api/v1/categories

List all categories with service counts

// example

curl "https://www.botfriendly.xyz/api/v1/categories"

GET/api/v1/featured

Get site-wide promoted/featured services (max 3). Clearly marked as ads.

// example

curl "https://www.botfriendly.xyz/api/v1/featured"

GET/api/v1/protocols

Protocol adoption stats — MCP, OpenAPI, MPP, x402, ACP, UCP

// example

curl "https://www.botfriendly.xyz/api/v1/protocols"

GET/api/v1/stats

Directory statistics — total services, per-category counts, protocol coverage

// example

curl "https://www.botfriendly.xyz/api/v1/stats"

POST/api/v1/verify

Check whether a service really exposes the interfaces it claims. Each endpoint you name is fetched and inspected, and the verdicts come back. Nothing is written and no auth is required — this is the same probe that runs on submissions, owner updates and discovery, exposed so an external workflow doesn't have to reimplement it and drift. Returns listable (did anything check out), verified (the flags that passed) and a probe result per claim. Rate limited to 60 calls/hour per IP.

// parameters

- url (required) — the service's own URL
- has_mcp_server, mcp_server_url — MCP server to probe
- has_openapi_spec, openapi_spec_url — OpenAPI spec to probe
- has_skill_file, skill_file_url — skill file to probe
- has_llms_txt, llms_txt_url — llms.txt to probe
- has_structured_feed, structured_feed_url — structured feed to probe

// example

curl -X POST "https://www.botfriendly.xyz/api/v1/verify" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","has_mcp_server":true,"mcp_server_url":"https://example.com/mcp"}'

POST/api/v1/submissions

Submit a new service. No auth required. Interface URLs must be on the service's own domain and are fetched during the request — the listing publishes immediately if one answers, or returns 422 with the probe results if none do. Every listing needs an icon: send icon_url or icon_base64, or leave both out and the service's own site is checked for one.

// parameters

- name (required) — service name
- url (required) — service URL
- category (required) — category slug
- description (required) — max 120 chars
- auth_method — api-key, m2m-oauth, bot-token, wallet, x402-none, none
- has_mcp_server, mcp_server_url — MCP server support
- has_openapi_spec, openapi_spec_url — OpenAPI spec support
- accepts_mpp, accepts_x402 — payment protocol support
- has_skill_file, has_llms_txt — integration files
- billing_model — pay-per-request, subscription, free, etc.
- has_free_tier — boolean
- tags — array of strings
- contact_email — for verification

// example

curl -X POST "https://www.botfriendly.xyz/api/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{"name":"YourService","url":"https://example.com","category":"browse","description":"What it does"}'

GET/api/v1/health

Health check and endpoint discovery

// example

curl "https://www.botfriendly.xyz/api/v1/health"

GET/api/v1/check

Score how bot-friendly a site is. Fetches it the way an agent would (no JavaScript) and reports access, no-JS content, and machine discovery out of 100, with advice per failed check. Rate limited to 6 checks/min per IP.

// parameters

- url (required) — site to check (scheme optional, https assumed)
- format — prompt returns a ready-to-paste coding-agent prompt covering every failed check, instead of the JSON report

// example

curl "https://www.botfriendly.xyz/api/v1/check?url=yourservice.dev"

>_docs --api

API reference for humans and agents

openapi.json llms.txt ai-plugin.json health

$ base url

https://www.botfriendly.xyz/api/v1

// No auth required. CORS enabled (*). JSON responses.

// Rate limits: 100 req/min by IP.

$ endpoints

GET/api/v1/services

List and filter all services. Returns paginated results with full protocol details.

// parameters

- category — filter by category slug (think, browse, pay, etc.)
- has_mcp=true — only services with MCP servers
- verified_interfaces — on every service, the badges we actually fetched and confirmed; a flag that is true but absent here is claimed, not verified
- accepts_mpp=true — only services accepting MPP
- accepts_x402=true — only services accepting x402
- has_skill_file=true — only services with skill files
- has_llms_txt=true — only services with llms.txt
- auth_method — filter by auth (api-key, m2m-oauth, bot-token, wallet, x402-none, none)
- search — full-text search across name, description, tags
- min_score — minimum bot-friendly score (1-5)
- sort — score (default), votes, name, newest
- promoted — true for promoted only, false for organic only
- page, per_page — pagination (default 1, 20; max 100)

// example

curl "https://www.botfriendly.xyz/api/v1/services?category=browse&has_mcp=true"

GET/api/v1/services/{slug}

Get full details for a single service including all protocol support, URLs, and metadata.

// example

curl "https://www.botfriendly.xyz/api/v1/services/browserbase"

GET/api/v1/search

Full-text search across services. Returns results ranked by bot_score.

// parameters

- q (required) — search query (supports websearch syntax)
- category — filter by category slug
- page, per_page — pagination (default 1, 20; max 100)

// example

curl "https://www.botfriendly.xyz/api/v1/search?q=vector+database"

GET/api/v1/categories

List all categories with service counts

// example

curl "https://www.botfriendly.xyz/api/v1/categories"

GET/api/v1/featured

Get site-wide promoted/featured services (max 3). Clearly marked as ads.

// example

curl "https://www.botfriendly.xyz/api/v1/featured"

GET/api/v1/protocols

Protocol adoption stats — MCP, OpenAPI, MPP, x402, ACP, UCP

// example

curl "https://www.botfriendly.xyz/api/v1/protocols"

GET/api/v1/stats

Directory statistics — total services, per-category counts, protocol coverage

// example

curl "https://www.botfriendly.xyz/api/v1/stats"

POST/api/v1/verify

// parameters

- url (required) — the service's own URL
- has_mcp_server, mcp_server_url — MCP server to probe
- has_openapi_spec, openapi_spec_url — OpenAPI spec to probe
- has_skill_file, skill_file_url — skill file to probe
- has_llms_txt, llms_txt_url — llms.txt to probe
- has_structured_feed, structured_feed_url — structured feed to probe

// example

curl -X POST "https://www.botfriendly.xyz/api/v1/verify" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","has_mcp_server":true,"mcp_server_url":"https://example.com/mcp"}'

POST/api/v1/submissions

// parameters

- name (required) — service name
- url (required) — service URL
- category (required) — category slug
- description (required) — max 120 chars
- auth_method — api-key, m2m-oauth, bot-token, wallet, x402-none, none
- has_mcp_server, mcp_server_url — MCP server support
- has_openapi_spec, openapi_spec_url — OpenAPI spec support
- accepts_mpp, accepts_x402 — payment protocol support
- has_skill_file, has_llms_txt — integration files
- billing_model — pay-per-request, subscription, free, etc.
- has_free_tier — boolean
- tags — array of strings
- contact_email — for verification

// example

curl -X POST "https://www.botfriendly.xyz/api/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{"name":"YourService","url":"https://example.com","category":"browse","description":"What it does"}'

GET/api/v1/health

Health check and endpoint discovery

// example

curl "https://www.botfriendly.xyz/api/v1/health"

GET/api/v1/check

// parameters

- url (required) — site to check (scheme optional, https assumed)
- format — prompt returns a ready-to-paste coding-agent prompt covering every failed check, instead of the JSON report

// example

curl "https://www.botfriendly.xyz/api/v1/check?url=yourservice.dev"

$ response format

Directory endpoints return JSON with a consistent envelope (/health returns a bare status object):

{
  "ok": true,
  "data": [...],
  "meta": {
    "total": 80,
    "page": 1,
    "per_page": 20,
    "total_pages": 4
  }
}

$ response headers

X-BotFriendly: true

X-API-Version: v1

X-OpenAPI-Spec: /api/v1/openapi.json

X-MCP-Server: /api/mcp

Access-Control-Allow-Origin: *

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 99

X-RateLimit-Reset: 1714000000

$ mcp server

BotFriendly has a remote MCP server that agents can connect to directly. Add it to Claude Desktop, Claude Code, or any MCP-compatible client.

// add to Claude Desktop

Settings → Connectors → Add custom connector:

Name: BotFriendly

URL: https://www.botfriendly.xyz/api/mcp

// add to Claude Code

claude mcp add botfriendly --transport http https://www.botfriendly.xyz/api/mcp

// tools

search_services — search and filter the directory

get_service — get full details for a service

get_featured — get site-wide featured services

list_categories — list all categories

submit_service — submit a new service

get_protocol_stats — protocol adoption stats

check_site — score how bot-friendly a website is (format: prompt for a fix-it prompt)

// Endpoint: /api/mcp