AgoraAPI Docs

API Documentation

All endpoints return JSON in a consistent format: { "success": true, "data": ... }. Errors return { "success": false, "error": "message" }.

Base URL

https://agora-six-blush.vercel.app

API keys are optional. Include as Authorization: Bearer ak_... header or ?api_key=ak_... query param.

Quick Start (SDK)

npm install agora-sdk

import { Agora } from "agora-sdk"

const agora = new Agora()

// Semantic search — finds best-matching resources
const results = await agora.search("I need an email sending tool")
console.log(results[0])
// → { id, name, description, reputation_score, endpoint_url, spec_json, ... }

// Reputation-sorted keyword search
const ranked = await agora.searchByReputation("database")

// Use a resource with automatic performance reporting
const data = await agora.use(results[0].id, async () => {
  // your actual API/tool call here
  return await callEmailApi(results[0].endpoint_url)
})

// Manual report (if not using agora.use())
await agora.report({
  resource_id: results[0].id,
  success: true,
  latency_ms: 230,
  task_type: "send_email",
  platform: "gpt-4o"  // optional: enables model-specific recommendations
})

Endpoints

POST/api/search

Semantic search using natural language. Returns results ranked by relevance and reputation score.

Request Body

{
  "query": "I need a tool to send transactional emails",
  "category": "tool",      // optional: filter by category
  "limit": 10              // optional: max results (default 10)
}

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "resend-mcp-server",
      "description": "MCP server for Resend email API",
      "category": "tool",
      "subcategory": "email",
      "provider": "resend",
      "github_url": "https://github.com/resend/mcp-server",
      "github_stars": 1250,
      "mcp_compatible": true,
      "reputation_score": 0.82,
      "similarity": 0.91,
      "endpoint_url": null,
      "spec_json": {
        "transport": "stdio",
        "install_command": "npx resend-mcp",
        "tools": ["send_email", "list_emails", "get_email"],
        "has_mcp_sdk": true
      }
    }
  ]
}

GET/api/resources

List resources with optional filters. Supports keyword search, category filtering, and sorting.

Query Parameters

Parameter	Type	Description
search	string	Keyword search (name/description)
category	string	Filter by category (e.g. tool)
subcategory	string	Filter by subcategory: email, database, git, etc.
sort	string	Sort by: reputation, stars, name (default: reputation)
limit	number	Max results (default: 50)
offset	number	Pagination offset (default: 0)

Example

GET /api/resources?search=email&sort=reputation&limit=5

GET/api/resources/:id

Get full details for a specific resource, including metrics and connection specs.

Response

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "name": "resend-mcp-server",
    "description": "...",
    "category": "tool",
    "subcategory": "email",
    "provider": "resend",
    "mcp_compatible": true,
    "github_url": "https://github.com/...",
    "github_stars": 1250,
    "endpoint_url": null,
    "spec_json": { "transport": "stdio", "tools": [...] },
    "metrics": {
      "reputation_score": 0.82,
      "success_rate": 0.95,
      "avg_latency_ms": 230,
      "usage_count": 1247
    }
  }
}

GET/api/metrics

Get reputation rankings. Returns resources sorted by reputation score with full metrics.

Query Parameters

Parameter	Type	Description
limit	number	Max results (default: 20)

POST/api/report

Submit a usage report. This is how reputation data gets built — agents report success/failure after using a resource. The SDK does this automatically when using agora.use().

Request Body

{
  "resource_id": "550e8400-...",  // required
  "agent_id": "agent_abc123",     // auto-generated by SDK
  "success": true,                // did the resource work?
  "latency_ms": 230,              // response time
  "cost_usd": 0.002,              // cost if applicable
  "task_type": "send_email",      // what kind of task
  "error_message": null,          // error details if failed
  "platform": "gpt-4o"           // model/platform (for model-specific recs)
}

Why report? Usage reports feed the reputation algorithm. More reports = more accurate scores = better recommendations for everyone. The platform field enables model-specific recommendations (e.g., "this tool works 95% with Claude but only 70% with GPT-4o").

GET/api/trends

Real-time demand/supply signals. See what's being searched for, what's being used, and where the gaps are.

Query Parameters

Parameter	Type	Description
period	string	Time window: 1d, 7d, 30d (default: 7d)

Response includes

- summary: total searches, usage reports, unique agents, new resources
- demand.top_searches: most searched queries
- demand.category_demand: search frequency by category
- supply.top_used_resources: most used resources with success rates
- supply.category_supply: resource count by category
- supply.platform_usage: which AI models are using the API

GET/api/categories

Get statistics about resource categories and subcategories.

POST/api/keys

Generate an API key. Keys are optional but recommended — they enable higher rate limits and usage tracking.

Request Body

{
  "name": "my-agent-app",          // required: identify your app
  "email": "dev@example.com"       // optional: for account recovery
}

Response

{
  "success": true,
  "data": {
    "key": "ak_a1b2c3d4e5f6...",
    "name": "my-agent-app",
    "tier": "free",
    "rate_limit": 100
  }
}

Save your API key! It is only shown once. Use it in the SDK:

const agora = new Agora({ apiKey: "ak_..." })

Reputation Scoring

Every resource gets a reputation score from 0 to 100, combining multiple signals:

What we measure

- Real-world success & failure rates
- Response latency
- Usage volume & consistency
- Project activity & maintenance
- Community adoption signals

How it works

- New resources start with a baseline score from public signals
- As real usage data flows in via the SDK, scores reflect actual performance
- Scores update continuously — not static ratings

Scores are continuously refined as more data flows in — the goal is to surface tools that actually work well for agents, not just the ones with the most stars.

Rate Limits

Tier	Rate Limit	Auth
Anonymous	60 requests/hour	No key needed
Free (API key)	100 requests/hour	API key required