The Recommendation API

Programmatic access to Hlido's review corpus. Buyer agents pass a free-text need plus optional constraints; Hlido returns a ranked shortlist with rationale, evidence URL, and a signed scorecard. Same ranker as the MCP server, exposed as REST for tools that don't speak JSON-RPC.

See pricing Open Swagger UI OpenAPI 3.1 JSON

Quickstart

Pick the surface that fits your stack. Free tier needs no key.

curl -X POST https://hlido.eu/v1/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "need": "code review tool with git integration",
    "constraints": { "category": "Coding", "min_tier": "STEADY" },
    "k": 1
  }'

# Free tier, no auth required
npx @hlido/cli recommend "code review tool"

# Paid tier, top-5 results
HLIDO_API_KEY=hlk_live_... npx @hlido/cli recommend \
  "voice agent for outbound sales" --k 5

const r = await fetch("https://hlido.eu/v1/recommend", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + process.env.HLIDO_API_KEY,
  },
  body: JSON.stringify({
    need: "code review tool",
    constraints: { category: "Coding", min_tier: "STEADY" },
    k: 5,
  }),
});
const { results } = await r.json();
console.log(results.map(x => x.slug + " " + x.score));

import os, requests

r = requests.post(
    "https://hlido.eu/v1/recommend",
    headers={"Authorization": f"Bearer {os.environ['HLIDO_API_KEY']}"},
    json={"need": "code review tool", "k": 5},
    timeout=10,
)
r.raise_for_status()
for hit in r.json()["results"]:
    print(hit["slug"], hit["score"], hit["evidence_url"])

Pricing

EUR-denominated, monthly. Stripe Tax enabled (VAT-inclusive in EU, exclusive elsewhere).

Free

€0/mo

100 calls/day per IP
Top-1 results only
Category filter
No API key needed

Anonymous quota is IP-keyed for 24h UTC. Best-effort SLA.

Dev

€9/mo

10,000 calls/month
Top-k up to 10
All constraints
Live API key
99.0% target SLA

Get a Dev key

Team

€19/mo

100,000 calls/month
Top-k up to 25
All constraints + custom rate burst
Live API key
99.5% target SLA

Get a Team key

Feature comparison

Feature	Free	Dev	Team
Monthly price	€0	€9	€19
Calls / period	100/day per IP	10,000/mo	100,000/mo
Top-k results	1	up to 10	up to 25
Category filter	Yes	Yes	Yes
All constraints (tier, score, freshness)	No	Yes	Yes
Custom rate burst	No	No	Yes
SLA target	Best-effort	99.0%	99.5%
API key	Not required	Live key	Live key

API keys can be managed at /account/ after sign-up. Lost keys must be re-minted; plaintext is shown once at creation and never re-fetchable.

Endpoints

POST /v1/recommend: Constraint-driven shortlist. Free tier forced to k=1.
GET /v1/agents/{slug}: Public scorecard summary (whitelist). ETag + 304.
GET /v1/categories: 13 canonical categories + counts.
GET /v1/health: Uptime + last_registry_update.
GET /v1/usage: Caller's tier + remaining quota.
GET /v1/stats/public: Daily aggregate counts.
GET /v1/incidents: Search published incidents (filter by slug, severity, since).
GET /v1/incidents/feed.xml: RSS feed of newly published incidents.

Full spec: /v1/openapi.json · Browse interactively in Swagger UI.

FAQ

What are the rate limits in detail?

Free: 100 calls per IP per UTC day, top-1 only. Bursts above 10 req/sec are throttled with HTTP 429 + Retry-After.

Dev: 10,000 calls/month, ~333/day soft cap, 30 req/sec sustained.

Team: 100,000 calls/month, no daily cap, 100 req/sec sustained, custom burst negotiable. Contact [email protected] if you need more headroom.

What's the SLA and what happens if you miss it?

Targets are 99.0% (Dev) and 99.5% (Team) measured monthly across all /v1/* endpoints, excluding scheduled maintenance windows announced 48h in advance. If we miss the target, paying customers receive a service credit pro-rated against their monthly fee, applied to the next invoice.

What's the refund policy?

30-day money-back guarantee on the first invoice for any reason. Beyond that, refunds are pro-rated for the remaining days in the current month if you cancel. Annual prepay (if available) is non-refundable except where required by EU consumer law.

Are scoring methodology weights exposed?

No. Scoring weights, dimension formulas, and the per-claim rubric stay private — that's the moat. Outcomes (slug, score, tier, summary, evidence URL, last_tested_at) are public-safe and the only fields the REST surface returns.

How do I authenticate?

Bearer token: Authorization: Bearer hlk_live_.... Free tier requires no header. Keys are minted at /account/ after sign-up; treat them as secrets.

Where do I report a bug or request a feature?

Email [email protected]. The public incident-submission form is in invitation-only beta until editorial cover finalises. Public roadmap pending.

Methodology privacy

Hlido's scoring weights, dimension formulas, and per-claim rubric stay private — that's the moat. Outcomes (slug, score, tier, summary, evidence URL, last_tested_at) are public-safe and the only fields exposed by the REST surface. We never expose dimension internals, peer-review fields, or anything from the brain pipeline state.

See our terms for detail, or read the methodology overview for what we test (without the weights).

Other surfaces

MCP server (JSON-RPC, no auth, 13 tools): /mcp
Public registry JSON: /data/review-registry.json
Per-agent scorecard JSON: /data/scorecards/{slug}.json
CLI: npm install -g @hlido/cli → hlido recommend "<need>"
Incident registry: /incidents/ · RSS