API Reference

Kerq API Docs

Everything you need to query trust scores, search tools, and integrate reliability signals directly into your agents and pipelines.

Base URL https://kerq.dev
⚡
5-minute setup
Quick Start

Get a trust score for any tool in under a minute. Three steps:

1. Get your API key at kerq.dev/developer

2. Query the trust score endpoint (curl)

# Replace YOUR_API_KEY and the tool slug
curl -s https://kerq.dev/api/tools/github-mcp-server/score \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Parse the response

{
  "success": true,
  "tool_id": 42,
  "slug": "github-mcp-server",
  "name": "GitHub MCP Server",
  "trust_score": 91,
  "tier": "certified",
  "score_breakdown": {
    "uptime": 98,
    "response_time": 95,
    "error_rate": 100,
    "consistency": 88,
    "throughput": 85,
    "recovery_behavior": 90,
    "dependency_stability": 82
  },
  "endpoint_ms": 124,
  "calculated_at": "2026-03-30T20:00:00.000Z"
}
ℹ
Use the score in your agent: If trust_score is below your threshold (e.g. 70), reject the tool connection or fall back to an alternative. Higher is more reliable.

Or use fetch (JavaScript)

const res = await fetch('https://kerq.dev/api/tools/github-mcp-server/score', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const { trust_score, tier } = await res.json();
if (trust_score < 70) throw new Error('Tool reliability below threshold');
🔑
API Keys
Authentication

Most Kerq API endpoints require an API key. Keys are tied to your developer account and your access tier (Free or High Volume).

Where to get a key: Sign up at kerq.dev, then visit the Developer Portal to generate and manage keys.

Three ways to pass your API key

# Option 1 — Authorization header (recommended)
Authorization: Bearer <your-api-key>

# Option 2 — X-API-Key header
X-API-Key: <your-api-key>

# Option 3 — Query parameter (useful for quick tests)
GET /api/tools/my-tool/score?api_key=<your-api-key>
ℹ
Keep your key secret. Treat API keys like passwords — don't commit them to public repos. Use environment variables: KERQ_API_KEY.

Missing key response

# HTTP 401
{
  "success": false,
  "error": "MISSING_API_KEY",
  "message": "API key required. Add header: Authorization: Bearer <your-api-key>",
  "docs": "https://kerq.dev/developer"
}
⚙
REST API
Endpoints
GET /api/tools/:id/score Auth required

The primary endpoint. Returns a live trust score and full 7-metric breakdown for any tool. Cached 6 hours with ETag support — safe to poll frequently.

Parameter Type Description
:id string required Tool ID (numeric) or slug (e.g. github-mcp-server)

Example response

{
  "success": true,
  "tool_id": 42,
  "slug": "github-mcp-server",
  "name": "GitHub MCP Server",
  "trust_score": 91,
  "tier": "certified",
  "score_breakdown": {
    "uptime": 98,
    "response_time": 95,
    "error_rate": 100,
    "consistency": 88,
    "throughput": 85,
    "recovery_behavior": 90,
    "dependency_stability": 82
  },
  "endpoint_ms": 124,
  "calculated_at": "2026-03-30T20:00:00.000Z"
}
GET /api/tools Auth required

Paginated list of all tools in the Score Index. Supports filtering by category, score threshold, and verification tier. Use this to build your own tool discovery layer.

Parameter Type Description
page integer optional Page number. Default: 1
limit integer optional Results per page. Default: 20, max: 100
search string optional Search tools by name or description
category string optional Filter by category slug
min_score integer optional Minimum trust score filter (0–100)
verification_tier string optional certified, community, or unverified
sort string optional Sort order (e.g. score_desc)

Example response

{
  "success": true,
  "tools": [
    {
      "id": 42,
      "slug": "github-mcp-server",
      "name": "GitHub MCP Server",
      "category": "Development",
      "trust_score": 91,
      "tier": "certified"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 347,
    "pages": 18
  }
}
GET /api/tools/:id Auth required

Full metadata for a single tool — name, description, category, endpoint URL, certification status, and current score.

Parameter Type Description
:id string required Tool ID (numeric) or slug

Example response

{
  "success": true,
  "tool": {
    "id": 42,
    "slug": "github-mcp-server",
    "name": "GitHub MCP Server",
    "description": "Official GitHub MCP server for code access",
    "category": "Development",
    "endpoint_url": "https://api.githubcopilot.com/mcp",
    "trust_score": 91,
    "tier": "certified",
    "is_certified": true,
    "is_claimed": true
  }
}
GET /api/tools/top Auth required

Leaderboard of the highest-scoring tools, sorted by trust score descending. Useful for surfacing reliable options when a user hasn't specified a tool.

Parameter Type Description
limit integer optional Number of results. Default: 20, max: 100
GET /api/health Public

Heartbeat endpoint. No auth required. Use this for uptime checks or pre-flight verification before your agent makes scored requests.

{
  "status": "ok",
  "timestamp": "2026-03-30T21:00:00.000Z"
}
📊
7 Metrics
Score Schema

Every tool is evaluated on 7 independent metrics. Each scores 0–100. The overall trust_score is a weighted composite.

Field Weight Description
uptime 30% Rolling availability over the measurement window. Downtime is the strongest negative signal.
response_time 20% Median latency in milliseconds. Sub-200ms scores very well; ≥5s scores 0.
error_rate 20% Proportion of probe requests that return error-class status codes (5xx). 2xx/401/403 score well; 5xx hurts.
consistency 10% Variance in response times. Low jitter = stable, well-provisioned service.
throughput 10% Ability to handle sustained load. Measured by response degradation under concurrent probes.
recovery_behavior 5% Speed of returning to healthy state after an error period. Fast recovery is a reliability signal.
dependency_stability 5% Disruption frequency attributable to the tool's own external dependencies (third-party APIs, CDNs, etc.).

Tier thresholds

Tier Score range Badge Description
Certified 70 – 100 🟢 Consistently reliable. Safe for production agents.
Community 55 – 69 🟡 Generally available. Occasional issues.
Unverified < 55 ⬜ No endpoint or unreliable. Use with caution.
ℹ
Recommended threshold for agents: Require trust_score >= 70 for tools your agent connects to in production. Use >= 55 for development and testing.
⏱
Quotas
Rate Limits
Plan Monthly calls Req/sec Cost
Free 10,000 / month 20 req/s $0
High Volume Unlimited 100 req/s $499 / month

Monthly quotas reset on your billing cycle date. If you exceed the Free tier limit, you'll get a 429 until the next reset. Upgrade any time from the Developer Portal.

There are no per-query charges on either plan. No surprise invoices.

Rate limit response headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1743638400
⚠
HTTP Status Codes
Errors

All error responses follow the same JSON format:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description of the problem"
}
Status Error code Cause
400 INVALID_PARAMS Missing or invalid query parameters
401 MISSING_API_KEY No API key in the request
401 INVALID_API_KEY Key does not exist or has been revoked
404 TOOL_NOT_FOUND No tool matches the provided ID or slug
429 RATE_LIMIT_EXCEEDED Monthly call quota exhausted. Resets on billing date.
500 INTERNAL_ERROR Unexpected server error. Retry with exponential backoff.

Questions? Email info@kerq.dev — we read everything.