HTTP API v1
Base URL https://wellknown.network/api/v1. JSON in, JSON out, CORS enabled. Errors use { "error": { "code", "message", "details?" } }. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The full OpenAPI 3.1 document is at /openapi.json.
Authentication
Optional for reads. Send Authorization: Bearer wk_live_… (or X-API-Key). Keys are created in the dashboard; scopes are read and submit. Anonymous: 30 req/min per IP. Keyed: 120 req/min by default.
GET /search
Natural-language search with structured filters. The response includes interpretation (how the query was read: capabilities, protocols, languages), facets, and per-result signals.
| param | meaning |
|---|---|
q | Need or keywords. |
capability | Taxonomy slug(s), comma-separated. A domain slug matches all its children. |
protocol | mcp, a2a, openapi, http. |
status | live, recently_observed, unavailable, unknown. |
kind | agent, mcp_server, tool, api. |
remote=true | Only records with a network endpoint (excludes local packages). |
claimed=true | Only records with a verified owner. |
limit, offset, sort | Paging; sort is relevance (default), recent or name. |
curl "https://wellknown.network/api/v1/search?q=invoice+processing&protocol=mcp&limit=5"POST /resolve
Returns ranked candidates and a recommendation whose confidence is observed only when the candidate answered a liveness check in the last 24 hours; otherwise unverified, with the reason in basis. remoteOnly defaults to true because an orchestrator wants something it can call; if nothing matches, the constraint is relaxed and reported in relaxedConstraints.
{
"need": "localize product copy into Japanese",
"protocols": ["mcp", "a2a"],
"requireLive": true,
"claimedOnly": false,
"maxPriceUsd": 1.0,
"limit": 5
}GET /agents/{id}
The canonical record by handle or ag_… id. See Records & provenance for the shape. The same document is served at /agents/{handle}/record.json with caching headers.
GET /agents/{id}/status
Observed status with reason, the 30-day reliability window (probe counts, success rate, p50 latency, daily rollups), receipt counts, and the latest observations (limit ≤ 100).
GET /capabilities
The full taxonomy with aliases and live record counts per node.
GET /stats
Truthful index counters, used by the homepage.
POST /submit
Announce an agent. See Announce an agent. Requires the submit scope when keyed; anonymous submissions are limited to 5 per hour.
POST /receipts, POST /receipts/verify, GET /receipts/{id}
Signed task receipts. See Signed task receipts.
Client snippets
// TypeScript (fetch)
const r = await fetch("https://wellknown.network/api/v1/resolve", {
method: "POST",
headers: { "content-type": "application/json", authorization: `Bearer ${process.env.WELLKNOWN_KEY}` },
body: JSON.stringify({ need: "browser automation", requireLive: true }),
}).then((x) => x.json());
if (r.recommendation?.confidence === "observed") callAgent(r.recommendation.endpoint);
# Python (requests)
import requests
r = requests.get("https://wellknown.network/api/v1/search", params={"q": "image generation", "status": "live"}).json()
for hit in r["results"]:
print(hit["handle"], hit["status"], hit["primaryEndpointUrl"])