Introduction

reputation·pool is a hosted reputation API for pools of interchangeable resources — proxies, accounts, sessions. You register the resources you own, ask the pool for one whenever you need it, and report what happened when you are done. In exchange, the pool stops handing out resources that keep failing, benches them for a cooldown, eases them back in when they look healthy again, and records every one of those decisions.

That loop is the whole product surface. There are three calls you will use constantly — Register, Acquire, Report — and a REST control plane for everything around them: keys, pool state, the audit trail, usage.

The signal is simple: you already have, or are about to write, code that decides which resource to use next and when to stop using one. That code always grows the same way — a cooldown map, then a blocklist, then per-endpoint exceptions, then a way to see why something was benched.

• Scraping / data-collection infrastructure rotating a proxy pool, where a burned proxy silently ruins a run instead of failing loudly.
• Account-based automation where a ban or a rate-limit on one account has to take that account out of rotation without taking the rest with it.
• Any pool with per-destination health — the same resource can be perfectly fine for one target and burned for another. That distinction is the core of the model; see Concepts.

It is a poor fit if your pool has one member, if resources are not interchangeable, or if you need routing decisions made from request payloads rather than from observed outcomes. The pool only knows what you report.

The service is split by traffic shape, and the split matters because the two halves authenticate differently.

• Data plane (gRPC). Register, Acquire, Report, Renew, Release, SubscribeEvents on the ReputationAdvisor service. This is the hot path your workers call. Authenticated with an API key in the x-api-key metadata header.
• Control plane (REST). /api/** — read pool state, read the audit trail, read usage, manage API keys. This is what the dashboard runs on and what your tooling scripts against. Authenticated with an admin JWT in the Authorization: Bearer header.

Both are documented here: Quickstart walks the data-plane loop, REST API reference covers the control plane, and Authentication explains which credential belongs where.

The decision engine is open source. Scoring, the four states and the transitions between them, the cooldown curve, lease fencing, and the selection strategy all live in PreAgile/reputation-pool under Apache-2.0, and this service consumes it as a published dependency rather than a fork. Everything a paragraph in Concepts says about behaviour is behaviour you can read the source of, and reproduce by self-hosting.

What the hosted service adds is everything around the engine:

• Multi-tenant isolation — one pool, audit trail, and event stream per tenant.
• API keys: issuing, hashed storage, rotation, immediate revocation.
• A durable audit trail with a query surface, plus a reputation-score time series.
• Usage metering, the dashboard, alerting, and running the thing.

• Quickstart — key to first Report, with curl, Java, and TypeScript.
• Concepts — the model: resources, contexts, cells, states.
• REST API reference — every control-plane endpoint and its errors.

Access is still onboarded by hand — there is no self-serve signup yet, and what onboarding grants you today is a tenant on the dashboard and the control plane, not a gRPC endpoint. Write to [email protected] and we will set up your tenant and a first key.