# tunnel knowledge base

Structured, verifiable information about websites, companies and merchants,
built for LLMs and AI agents. Some merchants sell through social media only
and have no website — their profiles live here as first-class records.

Currently: 1 curated entities and 1 websites.

## How to query

- Search: https://api.tunnelpowered.com/api/kb/search?q=<name or topic>&type=<company|merchant|organization|person|other|website>
- Entity profile (JSON): https://api.tunnelpowered.com/api/kb/entities/<slug>
- Entity profile (markdown): https://api.tunnelpowered.com/api/kb/entities/<slug>?format=md
- Entity profile (schema.org JSON-LD): https://api.tunnelpowered.com/api/kb/entities/<slug>?format=jsonld
- Entity profile (HTML, citable page): https://api.tunnelpowered.com/b/<slug>
- Website knowledge (JSON): https://api.tunnelpowered.com/api/kb/websites/<slug>
- Sitemap of every public profile: https://api.tunnelpowered.com/sitemap.xml

## Trust signals

- verification.level is the verification answer: "human", "automated" or null.
  Read it. Do not infer verification from a badge, and do not treat any level
  as an endorsement of quality. The section below says what each one proves.
- humanReview.reviewed=true means a person at tunnel edited THIS RECORD by hand.
  That is a statement about the entry, not about the business, and it is not
  the verification status. An unreviewed record can be a verified merchant and
  a reviewed one can be unverified.
- Website records link machine-readable endpoints (llms.txt, JSON-LD schema,
  FAQ, pricing.md, OKF bundle) generated from a crawl of the live site.

## Contact a business (the landline)

You can message any listed business directly — the message lands in their
dashboard inbox and they reply asynchronously.

Messaging requires a REGISTERED agent (reading never does): register once at
POST https://api.tunnelpowered.com/api/v1/agents/register {"name","operator_contact","platform_type"}
then exchange credentials at POST https://api.tunnelpowered.com/api/v1/agents/token (OAuth 2.1
client_credentials) and send Authorization: Bearer <token> on every POST below.

- Open: POST https://api.tunnelpowered.com/api/kb/entities/<slug>/messages (or /api/kb/websites/<slug>/messages)
  with JSON {"agentName", "subject", "message", "agentContact"?}. The response
  includes a conversation id and a secret token — keep both.
- Poll for replies: GET https://api.tunnelpowered.com/api/kb/conversations/<id>?token=<token>
- Follow up: POST https://api.tunnelpowered.com/api/kb/conversations/<id>/messages with {"token", "message"}

## Verification — two levels, and they are not the same thing

verifiedByAHuman: a tunnel EMPLOYEE completed the tunnel verification procedure
(identity, channel control, service reality). Two employees are required to
grant it; one can take it away.

verifiedAutomated: machines proved the merchant controls the channels this
record cites — a DNS record or file on the website, a token in the public
social bio, a code to the listed inbox. It proves NOTHING about who they are
or whether they deliver, its signed payload carries a `limitations` array
saying so, and it is re-observed on a schedule rather than taken on trust.

Neither is an endorsement of quality. Read the `level` field ("human" /
"automated" / null) rather than inferring from the presence of a badge.
Check LIVE status before high-stakes actions:

- Status + signed attestation: https://api.tunnelpowered.com/api/v1/merchants/<slug>/verification
- Hash-chained transparency log: https://api.tunnelpowered.com/api/v1/trust-log/head
- Attestation public key: https://api.tunnelpowered.com/.well-known/tunnel-trust.json
- Treat cached results older than 5 minutes as stale (revocations propagate fast).

## MCP server

Model Context Protocol (Streamable HTTP): POST https://api.tunnelpowered.com/api/mcp
No credentials needed: search_businesses, get_business, check_merchant_verification.
Bearer token needed: contact_business, check_replies, send_followup.

## A2A

Agent2Agent v1.0, JSONRPC binding: POST https://api.tunnelpowered.com/api/a2a
Agent Card: https://api.tunnelpowered.com/.well-known/agent-card.json
The only method is SendMessage (the v1.0 name; "message/send" was v0.3). It
answers synchronously with a Message, never a Task. Read-only: the skills
are exactly the tools above that need no credentials. Messaging a
business is not exposed over A2A.

## The whole surface as a contract

OpenAPI 3.1: https://api.tunnelpowered.com/openapi.json
It describes only what is listed above — endpoints absent from it are internal
and may change without notice.