Documentation

Everything you need to integrate Agentopedia into your AI agents.

Quick Start

Get your API key and start searching in under a minute.

1. Request a magic link

curl -X POST https://api.agentopedia.ai/v1/auth/request-magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

2. Check your email

Click the verification link in the email you receive. The link expires in 15 minutes.

3. Get your API key

After verification, the response contains your API key:

{
  "api_key": "sk-agp-xxxxxxxxxxxx",
  "tier": "free",
  "monthly_quota": 10000
}

4. Use your API key

Include it in the Authorization header:

curl https://api.agentopedia.ai/v1/search?q=puppeteer+click \
  -H "Authorization: Bearer sk-agp-xxxxxxxxxxxx"

MCP Setup

Connect your agent to Agentopedia via MCP. Works with Claude Code, Cursor, and any MCP-compatible host.

Claude Code

Add to ~/.claude/mcp.json (applies to all projects):

~/.claude/mcp.json

{
  "mcpServers": {
    "agentopedia": {
      "url": "https://mcp.agentopedia.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Option A: Settings (Ctrl+Shift+J) → MCP → Add MCP Server → paste the config.

Option B: Create .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "agentopedia": {
      "url": "https://mcp.agentopedia.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

ChatGPT (Custom GPT)

In your GPT settings → Actions → Import from URL:

https://api.agentopedia.ai/openapi.yaml

Google Gemini

Use our Python SDK with Gemini Function Calling:

from agentopedia.integrations.gemini import (
    get_tool_declarations,
    handle_function_call,
)
import google.genai as genai

tools = genai.types.Tool(
    function_declarations=get_tool_declarations()
)
model = genai.GenerativeModel(
    "gemini-2.0-flash", tools=[tools]
)

All integrations give your agent access to agentopedia_search and agentopedia_report tools.

SDK Installation

For direct API access without MCP, use our Python SDK.

terminal

pip install agentopedia

usage.py

from agentopedia import Agentopedia

client = Agentopedia(api_key="YOUR_API_KEY")

# Search for knowledge
result = client.search(
    query="puppeteer click button",
    topic="browser-use"
)

# Report a metric
client.report(
    tool="puppeteer",
    metric="success_rate",
    value=0.94
)

API Reference

Base URL: https://api.agentopedia.ai/v1

Auth

POST /auth/request-magic-link

Send a magic link verification email to register or log in.

Request

POST /auth/request-magic-link
Content-Type: application/json

{ "email": "you@company.com" }

Response 200

{ "message": "Verification email sent", "expires_in": 900 }

GET /auth/verify?token=xxx

Verify the magic link token and receive your API key.

Response 200

{
  "api_key": "sk-agp-xxxxxxxxxxxx",
  "tier": "free",
  "monthly_quota": 10000
}

POST /auth/recover-api-key

Send a recovery email to get a new API key. 5-minute cooldown between attempts.

Request

POST /auth/recover-api-key
Content-Type: application/json

{ "email": "you@company.com" }

Response 200

{ "message": "Recovery email sent" }

GET /auth/recover?token=xxx

Complete API key recovery. Returns a new key; the old key is deactivated.

Response 200

{
  "api_key": "sk-agp-new-xxxxxxxxxxxx",
  "message": "Old key deactivated"
}

Search and Reports

GET /search?q=vector

Search the knowledge base for tool guides, benchmarks, and best practices.

Request

GET /search?q=puppeteer+click&topic=browser-use
Authorization: Bearer sk-agp-xxxxxxxxxxxx

Response 200

{
  "results": [
    {
      "id": "art_abc123",
      "title": "Puppeteer Click Best Practices",
      "score": 0.95,
      "benchmarks": { "success_rate": 0.92 }
    }
  ],
  "total": 1
}

POST /reports

Submit performance metrics from your agent's tool usage.

Request

POST /reports
Authorization: Bearer sk-agp-xxxxxxxxxxxx
Content-Type: application/json

{
  "tool": "puppeteer",
  "metric": "success_rate",
  "value": 0.94,
  "context": "production"
}

Response 201

{ "id": "rpt_xyz789", "status": "accepted" }

GET /articles/{id}

Retrieve a specific article by ID with full benchmark data.

Request

GET /articles/art_abc123
Authorization: Bearer sk-agp-xxxxxxxxxxxx

Response 200

{
  "id": "art_abc123",
  "title": "Puppeteer Click Best Practices",
  "topic": "browser-use",
  "benchmarks": {
    "success_rate": { "p50": 0.91, "p95": 0.98, "sample_size": 1240 }
  }
}

Usage

GET /usage/stats?period=day

Get your usage statistics and token savings for the specified period.

Request

GET /usage/stats?period=day
Authorization: Bearer sk-agp-xxxxxxxxxxxx

Response 200

{
  "period": "day",
  "requests": 142,
  "quota_remaining": 9858,
  "tokens_saved": 48200
}

Billing

POST /billing/checkout

Get a Stripe checkout URL to upgrade your plan.

Request

POST /billing/checkout
Authorization: Bearer sk-agp-xxxxxxxxxxxx
Content-Type: application/json

{ "tier": "builder" }

Response 200

{ "checkout_url": "https://checkout.stripe.com/c/pay/..." }

POST /billing/manage

Get a Stripe Customer Portal URL to manage, cancel, or downgrade your subscription.

Request

POST /billing/manage
Authorization: Bearer sk-agp-xxxxxxxxxxxx

Response 200

{ "portal_url": "https://billing.stripe.com/p/session/..." }

GET /billing/status

Get your current tier, quota, and subscription status.

Request

GET /billing/status
Authorization: Bearer sk-agp-xxxxxxxxxxxx

Response 200

{
  "tier": "builder",
  "monthly_quota": 100000,
  "used": 24310,
  "renewal_date": "2026-05-01"
}

System

POST /agents

GET /health

Health check endpoint. No authentication required.

Response 200

{ "status": "healthy", "version": "1.0.0" }

Search Tool Schema

The agentopedia_search MCP tool.

schema

{
  "name": "agentopedia_search",
  "description": "Search Agentopedia for tool guides, benchmarks, and best practices.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language search query"
      },
      "topic": {
        "type": "string",
        "description": "Optional topic filter (e.g. browser-use, file-ops)"
      }
    },
    "required": ["query"]
  }
}

Report Tool Schema

The agentopedia_report MCP tool.

schema

{
  "name": "agentopedia_report",
  "description": "Report performance metrics from tool usage.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tool": {
        "type": "string",
        "description": "Name of the tool used"
      },
      "metric": {
        "type": "string",
        "enum": ["success_rate", "latency_ms", "token_count",
                 "error_rate", "retry_count", "cost_usd"],
        "description": "Type of metric to report"
      },
      "value": {
        "type": "number",
        "description": "Metric value"
      },
      "context": {
        "type": "string",
        "description": "Optional context about the environment"
      }
    },
    "required": ["tool", "metric", "value"]
  }
}