Developer Docs

Bothub REST API

Machine-readable. LLM-friendly. Search agents across all categories, embed trust badges, access market intelligence, and self-register via API.

Get API Token MCP Server (npm)BAIP SDK (npm)Smithery →

Base URL

https://bothub.tech

HTTPS only. JSON responses. ISO 8601 UTC timestamps. CORS enabled on all public endpoints.

Authentication

Most GET endpoints are public. Endpoints marked Auth required need a PAT from /dashboard/tokens.

Authorization: Bearer bh_your_token_here

# Or via header:
X-API-Key: bh_your_token_here

agents:read

Read agent data (default for public GET)

agents:write

Submit + update agents via API

watchlist:write

Manage watchlist programmatically

120 req/min

Public GET

No auth required

300 req/min

Authenticated

PAT token

10 req/hour

Agent submission

Per user

Endpoints (17)

GET

/api/v1/agents

List approved agents with filtering, sorting, and pagination. Public access, rate limited to 120 req/min.

Parameters

pagenumberPage number (default: 1)

limitnumberItems per page, max 100 (default: 20)

qstringFull-text search on title, description, creator

categorystringCategory slug (e.g. coding, security, chatbots)

sortstringscore | trending | watchers | new (default: score)

Example

curl "https://bothub.tech/api/v1/agents?sort=score&limit=3"

Response

{
  "data": [
    {
      "slug": "microsoft-copilot",
      "title": "Microsoft Copilot",
      "agent_type": "copilot",
      "market_score": 16,
      "claim_status": "unclaimed",
      "pricing_type": "freemium",
      "short_description": "...",
      "url": "https://bothub.tech/agents/microsoft-copilot"
    }
  ],
  "pagination": { "page": 1, "limit": 3, "total": 430, "pages": 144 }
}

GET

/api/v1/agents/{slug}

Full agent detail including scores, trust data, category, model stack, and integrations.

Parameters

slugstringrequiredAgent slug from listing URL

Example

curl "https://bothub.tech/api/v1/agents/claude-code"

Response

{
  "slug": "claude-code",
  "title": "Claude Code",
  "agent_type": "copilot",
  "market_score": 15,
  "trend_score": 42,
  "trust_score": 24,
  "claim_status": "unclaimed",
  "verification_level": 1,
  "watchers_count": 0,
  "upvotes": 0,
  "page_views": 12,
  "primary_category": { "name": "Coding Agents", "slug": "coding" },
  "model_stack": ["claude-sonnet-4.6"],
  "website_url": "https://claude.ai/code",
  "badges": [],
    "trust": {
      "verification_level": 1,
      "claim_status": "unclaimed",
      "featured": false,
      "behavioral_exposure": {
      "public_score": 38,
      "public_tier": "guarded",
      "confidence_level": "automated",
      "review_status": "not_needed",
      "mismatch_delta": null,
      "automated": { "score": 38, "tier": "guarded", "summary": "Automated baseline from public evidence." },
      "declared": null,
      "verified": null,
      "summary": "Pre-deployment exposure is guarded due to limited read access, approval-gated automation, access to source code."
    }
  }
}

GET

/api/v1/agents/{slug}/history

Score history snapshots for charting BMS trends. Up to 90 data points.

Parameters

slugstringrequiredAgent slug

limitnumberMax snapshots (1–90, default 30)

daysnumberFilter to last N days

Example

curl "https://bothub.tech/api/v1/agents/cursor/history?limit=7"

Response

{
  "slug": "cursor",
  "current_score": 15,
  "delta_pct": 0,
  "snapshots": [
    { "score": 15, "trend": 38, "upvotes": 0, "rank": 5, "recorded_at": "2026-04-05T00:00:00Z" }
  ],
  "total": 7
}

GET

/api/v1/categories

All categories. Use the slug when filtering agents or registering.

Example

curl "https://bothub.tech/api/v1/categories"

Response

[
  {
    "id": "uuid",
    "name": "Coding Agents",
    "slug": "coding",
    "icon": "Code",
    "description": "AI agents for software development",
    "url": "https://bothub.tech/category/coding"
  },
  { "name": "MCP Servers", "slug": "mcp-servers", "icon": "🔌", "..." },
  { "name": "Agent Frameworks", "slug": "agent-frameworks", "icon": "🏗️", "..." },
  { "name": "Language Models", "slug": "language-models", "icon": "🧠", "..." }
]

GET

/api/v1/categories/trends

Category trend data — agent counts, growth rates, and top agents per category.

Example

curl "https://bothub.tech/api/v1/categories/trends"

Response

{ "categories": [...], "generated_at": "2026-04-05T..." }

GET

/api/v1/market-report

Market intelligence report with Fear & Greed Index, sector rotation, and verification stats.

Example

curl "https://bothub.tech/api/v1/market-report"

Response

{ "fear_greed_index": {...}, "sector_rotation": [...], "verification_stats": {...} }

GET

/api/v1/weekly-report

Weekly market summary with top agents, trending, new listings, and shareable Twitter/LinkedIn snippets.

Example

curl "https://bothub.tech/api/v1/weekly-report"

Response

{
  "title": "Bothub Weekly Report — Mar 30 to Apr 5, 2026",
  "summary": { "total_agents": 430, "new_agents_this_week": 5 },
  "top_10_by_score": [...],
  "trending_this_week": [...],
  "shareable_snippets": {
    "twitter": "📊 Bothub Weekly: 430 agents, top: Microsoft Copilot...",
    "linkedin": "The AI agent market this week: ..."
  }
}

GET

/api/v1/leaderboard

Launch leaderboard with velocity-scored ranking of recently launched agents.

Example

curl "https://bothub.tech/api/v1/leaderboard"

Response

{ "leaderboard": [...], "generated_at": "..." }

GET

/api/v1/incidents

Public incident registry for AI agent misbehavior, exploits, and outages.

Example

curl "https://bothub.tech/api/v1/incidents"

Response

{ "incidents": [...], "total": 0 }

GET

/api/v1/enterprise/agents

Enterprise bulk API with field selection and CSV export. Metered: 300 req/min auth, 10 req/min public.

Parameters

formatstringjson (default) or csv

fieldsstringComma-separated field names to include

Example

curl "https://bothub.tech/api/v1/enterprise/agents?format=csv&fields=title,market_score,agent_type"

Response

title,market_score,agent_type
Microsoft Copilot,16,copilot
n8n AI,15,agent
...

POST

/api/v1/agents/register Auth required

Request Body (JSON)

titlestringrequiredAgent name (2–120 chars)

website_urlstringrequiredCanonical URL

short_descriptionstringOne-liner (max 280 chars)

pricing_typestringfree | freemium | paid | usage-based | enterprise

category_slugstringFrom GET /api/v1/categories

model_stackstring[]Models used: ["claude-sonnet-4.6"]

docs_urlstringDocumentation URL

github_urlstringGitHub repository URL

creator_namestringCompany or individual name

behavioral_profileobjectOptional paid self-attested behavioral declaration. Free listings still receive an automated baseline.

Example

curl -X POST "https://bothub.tech/api/v1/agents/register" \
  -H "Authorization: Bearer bh_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My AI Agent",
    "website_url": "https://myagent.ai",
    "agent_type": "agent",
    "pricing_type": "freemium",
    "category_slug": "coding",
    "behavioral_profile": {
      "access_scope": "workspace_read",
      "effect_scope": "suggest_only",
      "autonomy_level": "approval_gated",
      "propagation_scope": "single_system",
      "containment_strength": "scoped",
      "recoverability_level": "rollback_ready",
      "sensitive_access": ["source_code"]
    }
  }'

Response

{
  "id": "uuid",
  "status": "pending",
  "message": "Queued for review. You will be notified once approved."
}

GET

/api/agents/{slug}/trust

Trust score breakdown — identity, verification, completeness, and badge status.

Example

curl "https://bothub.tech/api/agents/cursor/trust"

Response

{
  "slug": "cursor",
  "trust_score": 24,
  "breakdown": { "identity": 0, "verification": 8, "completeness": 16 },
  "claim_status": "unclaimed",
  "verification_level": 1,
  "badges": []
}

GET

/api/agents/{slug}/manifest

BAIP v2 manifest — machine-readable agent identity card. Cached 1 hour.

Example

curl "https://bothub.tech/api/agents/cursor/manifest"

Response

{
  "bothub_version": "2.0",
  "identity": { "name": "Cursor", "slug": "cursor", "type": "copilot" },
  "urls": { "website": "https://cursor.sh", "bothub": "https://bothub.tech/agents/cursor" },
  "trust": { "score": 24, "level": 1, "claim_status": "unclaimed" },
  "market": { "bms": 15, "trend": 38, "rank": 5 }
}

GET

/api/badges/{slug}

Embeddable SVG rank badge for READMEs and websites. No auth. Cached 1 hour.

Parameters

stylestringdefault (rank + score) or trust (verification level)

Example

<!-- Rank badge -->
![Bothub](https://bothub.tech/api/badges/my-agent)

<!-- Trust badge -->
![Bothub Trust](https://bothub.tech/api/badges/my-agent?style=trust)

<!-- As link -->
[![Bothub](https://bothub.tech/api/badges/my-agent)](https://bothub.tech/agents/my-agent)

Response

<!-- SVG image: "Listed on Bothub · #12 · 15" -->
<!-- Trust variant: "Bothub Reviewed · Score 15" -->
<!-- Cache: s-maxage=3600 -->

GET

/api/og/{slug}

Dynamic 1200×630 OG share card. Auto-used by Twitter/LinkedIn when sharing agent URLs.

Example

<meta property="og:image" content="https://bothub.tech/api/og/my-agent" />

Response

<!-- PNG 1200×630 with rank, score, category, pricing, trend -->

GET

/.well-known/ai-plugin.json

OpenAI plugin discovery manifest. Describes Bothub's API for LLM tool use and XIIS-aware registry access.

Example

curl "https://bothub.tech/.well-known/ai-plugin.json"

Response

{ "schema_version": "v1", "name_for_model": "bothub", "api": { "type": "openapi" } }

GET

/llms.txt

LLM-readable platform index. Lists all endpoints, categories, and top 200 agents.

Example

curl "https://bothub.tech/llms.txt"

Response

# Bothub — The XIIS Registry and Trust Layer for AI Agents
# 430+ agents across 33 categories...
## Platform Pages
- Agent directory: https://bothub.tech/agents
...

Ready to integrate?

Get a PAT token, register your agent, and start climbing the rankings.

Get API Token Submit via UI instead