# For agents

Three endpoints. Find the entry that covers an error, narrow it to the one cause you actually have, and say what happened. No key, no rate limit, no signup — the corpus is CC-BY-4.0 and the point of it is to be used.

Interface at a glance
Base	https://knowbase.sh
Auth	None
Entries	25
Index for models	/llms.txt

## 1. Look it upGET /search.json

Paste the error message, the error code, or the whole stack trace. Boilerplate in a traceback discounts itself, so you do not need to clean it first.

bash

curl -s 'https://knowbase.sh/search.json?q=deadlock+detected'

The response carries a match field:

strong — one entry covers this. Read its notApplicableTo before applying it.
partial — related, but may be a different failure. Leads to verify, not the answer.
none — not covered here. The result list is empty on purpose.

On none we return nothing rather than the closest entry. A near-miss answer to a production failure is worse than no answer, and an agent being told plainly that a source does not cover something is more useful than a confident guess.

## 2. Narrow it to one causePOST /diagnose.json

Every entry lists four to six possible causes, and each carries a discriminator — the cheap check that tells you whether it is yours. Run them, then post what they returned.

bash

curl -s -X POST 'https://knowbase.sh/diagnose.json' \
  -H 'content-type: application/json' \
  -d '{
    "lookupId": "<from the lookup response>",
    "slug": "kubernetes-imagepullbackoff",
    "observations": "Events show 401 Unauthorized and pull access denied"
  }'

You get back the one cause your observations identify, and the ruled-out causes each paired with the check that rules it out — which the lookup alone cannot tell you. When nothing leads clearly the answer is identified: null, with the candidates ordered by fit.

This is the call worth making. Documentation everywhere lists what can cause an error; nothing records which cause actually fires, or how often. That only exists where the checks get run.

## 3. Say what happenedPOST /outcome.json

bash

curl -s -X POST 'https://knowbase.sh/outcome.json' \
  -H 'content-type: application/json' \
  -d '{"slug": "kubernetes-imagepullbackoff", "worked": true}'

Optional, and deliberately thin. The signal is weak and we know why: there is no way to tell whether the entry solved it or you already knew, failures under-report worse than successes, and none of it is verifiable.

## What reporting cannot do

Nothing posted to either endpoint can raise or lower an entry’s stated confidence. That label is gated on evidence — source count and source type — and a second, weaker path to the same label would empty it of meaning. Usage is popularity, not proof.

What reports do earn is a place in the queue: which entry gets re-checked against its sources, and which failure gets written up next. See the method for how confidence is actually assigned.

## Other ways in

Any entry is available as JSON, Markdown or plain text by appending an extension — /k/<slug>.json, .md, .txt — and Accept: text/markdown on the HTML URL returns the Markdown twin. For a single fetch of everything, use /llms-full.txt.

An MCP server is not published yet. It would be a thin wrapper over these three calls, so nothing here changes when it lands — code written against this interface keeps working. Until then any agent with HTTP can use knowbase, which is why the endpoints came first.

## Stability

Every JSON body carries schemaVersion. Fields get added; existing ones will not change meaning under you. The endpoints answer OPTIONS and send access-control-allow-origin: *, so they work from a browser as well as a server.

Requests are logged: the query, the verdict, which entry we pointed at, and the user-agent. Queries are truncated and patterns that look like tokens, passwords or credentials in a connection string are stripped before storage.