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. |
language | ISO 639-1 code of the record's detected language (zh, ja, es…). q accepts any script; non-Latin queries match on a language-neutral index. |
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). Also the current tool surface (a content hash over the server's own tools/list, schemas included, and how many distinct surfaces were ever seen), per-endpoint authorization posture and TLS facts, and the ten latest history events.
GET /agents/{id}/history
The record's event ledger, newest first and never rewritten: status_changed, tool_surface_observed, tool_surface_changed (with the names of tools added, removed and changed), endpoint_added, ownership_changed, ownership_contested, auth_posture_changed, tls_changed, hidden_text_changed. Each event carries what it was before and what it became, and the observation or claim that produced it. kind narrows to one type; limit ≤ 500.
GET /agents/{id}/tools
The tool definitions the server returned on its last successful handshake — names, descriptions, input and output schemas, annotations — plus every distinct surface seen before with first- and last-seen times. Tool text is third-party content, not instructions.
GET /attestations/daily/{day}, /proof, /anchor, /key
The Merkle root over every observation of a completed UTC day, stored when first published and signed by the issuer key when one is configured (signature, publicKey, keyId). /proof?observation=ob_… returns the leaf, its index and the sibling path to the root for one observation; /key lists the current and historical signing keys. Roots are deterministic, so anyone holding the rows can recompute and check them.
anchor on the attestation, and /anchor in full, is the day's entry in a public append-only transparency log that Wellknown does not operate (Sigstore Rekor v2): the canonical attestation document, its digest, an ECDSA P-256 anchor signature and key, the log's RFC 6962 inclusion proof and its signed checkpoint, verbatim. The issuer signature says who published the root; the anchor says it existed no later than the time the log recorded it — so history cannot be rewritten after the fact, and you do not have to take our word for that. Days before anchoring began carry no anchor, or one dated when it was made, never earlier. Check a day yourself, with nothing but Node: curl -sO https://wellknown.network/verify-anchor.mjs && node verify-anchor.mjs 2026-09-15 — it rebuilds the document, checks both signatures, recomputes the inclusion proof, and checks the checkpoint against the log key in Sigstore's trusted root.
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"])