Kerq API Docs

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,
    "performance_trend": 80
  },
  "endpoint_ms": 124,
  "calculated_at": "2026-03-30T20:00:00.000Z"
}

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');

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>

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"
}

Rate limit response headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1743638400

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description of the problem"
}

{
  "tool_id": "github-mcp-server",
  "status_code": 200,
  "latency_ms": 145,
  "timestamp": "2026-04-07T19:14:00.000Z"
}

{
  "success": true,
  "message": "Telemetry recorded",
  "is_outlier": false
}

curl example

POST https://kerq.dev/api/v1/report

curl -s -X POST https://kerq.dev/api/v1/report \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"github-mcp-server","status_code":200,"latency_ms":145}'

JavaScript (fetch)

const t0 = Date.now();
const response = await fetch(toolEndpoint, { method: 'POST', body: payload });
const latency_ms = Date.now() - t0;

// Fire-and-forget — don't await in your critical path
fetch('https://kerq.dev/api/v1/report', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KERQ_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tool_id: 'github-mcp-server',
    status_code: response.status,
    latency_ms
  })
}).catch(() => {}); // never let telemetry throw

Python (requests)

import time, requests, os

t0 = time.monotonic()
resp = requests.post(tool_endpoint, json=payload, timeout=10)
latency_ms = int((time.monotonic() - t0) * 1000)

# Report to Kerq (best-effort, non-blocking in production)
try:
    requests.post(
        "https://kerq.dev/api/v1/report",
        json={
            "tool_id": "github-mcp-server",
            "status_code": resp.status_code,
            "latency_ms": latency_ms
        },
        headers={"Authorization": f"Bearer {os.environ['KERQ_API_KEY']}"},
        timeout=2
    )
except Exception:
    pass  # telemetry is optional — never block on it

Load via script tag (browser)

<script src="https://kerq.dev/kerq-sdk.js"></script>
<script>
  const kerq = window.kerq.createClient('YOUR_API_KEY');
</script>

Node.js (CommonJS)

const { createClient } = require('./kerq-sdk');
const kerq = createClient(process.env.KERQ_API_KEY);

Basic usage — plain data

// After a tool call completes, report it:
await kerq.reportTelemetry('github-mcp-server', {
  status_code: 200,
  latency_ms: 145
});

// With an explicit timestamp:
await kerq.reportTelemetry('slack-mcp', {
  status_code: 503,
  latency_ms: 4200,
  timestamp: new Date().toISOString()
});

With a fetch Response object

const t0 = Date.now();
const response = await fetch(toolEndpointUrl, options);
const latency_ms = Date.now() - t0;

// Pass the Response directly — SDK extracts status automatically
kerq.reportTelemetry('my-mcp-tool', response, { latency_ms }); // fire-and-forget

Express.js middleware pattern

// middleware/kerq-telemetry.js
const { createClient } = require('./kerq-sdk');
const kerq = createClient(process.env.KERQ_API_KEY);

function kerqTelemetry(toolId) {
  return async function(req, res, next) {
    const t0 = Date.now();
    res.on('finish', () => {
      kerq.reportTelemetry(toolId, {
        status_code: res.statusCode,
        latency_ms: Date.now() - t0
      }); // fire-and-forget
    });
    next();
  };
}

// Usage:
app.post('/call-github-tool', kerqTelemetry('github-mcp-server'), handler);

Axios interceptor pattern

const axios = require('axios');
const { createClient } = require('./kerq-sdk');
const kerq = createClient(process.env.KERQ_API_KEY);

axios.interceptors.request.use(config => {
  config.metadata = { t0: Date.now() };
  return config;
});

axios.interceptors.response.use(
  response => {
    const latency_ms = Date.now() - response.config.metadata.t0;
    kerq.reportTelemetry(response.config.headers['X-Kerq-Tool-Id'], {
      status_code: response.status,
      latency_ms
    });
    return response;
  },
  error => {
    if (error.response) {
      const latency_ms = Date.now() - error.config.metadata.t0;
      kerq.reportTelemetry(error.config.headers['X-Kerq-Tool-Id'], {
        status_code: error.response.status,
        latency_ms
      });
    }
    return Promise.reject(error);
  }
);