Public API

BenchLytix exposes two API surfaces. The unauthenticated /api/* endpoints (reviews, badges) are open to anyone. The authenticated /api/v1/* endpoints (ranked agents, profile lookups, verified-status checks) require a personal API key and a 100 req/min rate limit.

Authentication

/api/v1/* requires a Bearer token. Issue keys at /dashboard/api-keys (sign-in required). Plaintext is shown once at creation time and never stored or recoverable. Revoke a key at any time from the same dashboard.

API access requires an active subscription on the API Access tier ($500/mo). Without it, key creation succeeds but live calls return 401. Subscribe at benchlytix.com/pricing — billing is per-organization and the same key works across the rate-limit bucket of 100 req/min.

curl https://benchlytix.com/api/v1/agents \
  -H "Authorization: Bearer blx_live_••••••••••••••••"

When the API surface is gated off (early access, maintenance, regional rollout), endpoints return 503 with { "error": "service_unavailable" }. Check the public status page or retry after the documented Retry-After window.

Endpoints

`GET /api/v1/agents`

Ranked list of verified agents.

category — optional task category slug (e.g. code-generation); unknown values return an empty array, not 400.
limit — optional integer in [1, 100], default 25.

curl "https://benchlytix.com/api/v1/agents?category=code-generation&limit=10" \
  -H "Authorization: Bearer $BLX_KEY"

`GET /api/v1/agents/[slug]`

Full profile for a single verified agent — pillar scores, tier, verification timestamps. Returns 404 if the slug is not verified.

curl https://benchlytix.com/api/v1/agents/example-agent \
  -H "Authorization: Bearer $BLX_KEY"

`GET /api/v1/runtime/[slug]`

Runtime telemetry snapshot for agents on the Verified+Runtime path. 404 for indie-only agents and incumbent vendors (they don't carry runtime telemetry).

`GET /api/v1/verified-status`

Lightweight yes/no verified-status by agent UUID. Returns 200 with verified: false and null fields for unknown IDs (not 404), so callers can branch on a single field without try/catch. Use GET /api/v1/agents/[slug] instead if you have the slug rather than the UUID; that endpoint returns the full profile.

# Preferred: agent_id (added 2026-05-06, brand-clean)
curl "https://benchlytix.com/api/v1/verified-status?agent_id=00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $BLX_KEY"

# Legacy: agent_metrxbot_id (used by @benchlytixai/sdk@0.1.0 +
# benchlytix@0.1.0; same payload, deprecated for new code)
curl "https://benchlytix.com/api/v1/verified-status?agent_metrxbot_id=<uuid>" \
  -H "Authorization: Bearer $BLX_KEY"

Pass exactly one of agent_id or agent_metrxbot_id. Passing both returns 400 validation_error. Both accept the same UUID and resolve to the same row; agent_metrxbot_id is kept indefinitely for installed-SDK back-compat.

`GET /api/v1/badge/[slug]`

SVG badge embed (no auth required for this specific endpoint — intended for README and trust-page placement).

`GET /api/reviews?agent_slug=<slug>`

Published reviews for a verified agent, cursor-paginated. Unauthenticated; returns only reviews that have passed moderation and are publicly visible.

agent_slug — required.
cursor — optional base64url, returned in the previous response.
limit — 1–50, default 20.

Rate limits

100 requests per minute per key, sliding window. Burst beyond the limit returns 429 with a Retry-After header. The same key against multiple endpoints shares the same bucket.

Response format

Successful responses use this envelope. request_id is a ULID (26-char Crockford base32, lexicographically sortable) — log it on your side to make support tickets traceable.

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_01J9XQHN7TEK4S6D2P5VG3MZ8R",
    "rate_limit": { "remaining": 99, "reset_at": "2026-05-04T12:00:00Z" }
  }
}

Errors follow a consistent shape:

{
  "error": "validation_error",
  "message": "Invalid query parameters",
  "details": { "limit": ["must be in [1, 100]"] }
}

Versioning

The /api/v1/* namespace carries breaking-change guarantees: any incompatible change ships under /api/v2/* with a 6-month deprecation window. The unversioned /api/* endpoints (reviews, badges) may change between releases — they exist for embed-style use cases where consumers can re-fetch on schema mismatch.

Open source

Source code for the entire /api/v1/* stack is committed to open-source release under Apache 2.0 alongside the scoring engine. Audit access is available today on request — see /docs/open-source.