HTTP API and MCP
Read attributable business facts without scraping a site.
Search the registry, inspect a signed passport, ask a scoped question, or check whether a domain meets a named trust policy. Missing evidence produces an explicit refusal; stale evidence may be refused or returned with an explicit stale flag, depending on the fact policy.
Overview
One registry, two integration surfaces
HTTP is useful for direct service integration. MCP exposes the same registry and answer logic as tools for compatible AI clients. Public reads stay available; ask, search, bulk and monitoring follow the published quota rules.
Public HTTP
Entity lists, passports, search, trust checks, the trust ladder and machine-readable plans.
Remote MCP
Six real tools over the same database and trust semantics.
Signed evidence
Passport hashes and, when enabled, detached Ed25519 signatures support integrity checks. They do not prove every submitted fact is true.
MCP connection
Connect a Streamable HTTP client
Add the remote URL below in a client that supports MCP Streamable HTTP. The exact settings screen or configuration shape depends on your client, so Intesta does not invent a universal client-specific file.
Server name: Intesta Transport: Streamable HTTP URL: https://intesta.io/mcp Optional header: Authorization: Bearer ik_your_key
Available MCP tools
check_trust(domain, purpose): signed decision aid for payment, data sharing or following instructions.
get_passport(entity_domain): public facts, sources, freshness and attestation proof.
ask(entity_domain, question): answer from matching passport facts or return an explicit refusal.
search_entities(query, limit): literal registry search over published entities.
list_entities(): up to 500 published entities plus the registry total.
get_trust_ladder(): machine-readable A0 to A4 semantics.
Authentication and quotas
Create a key in the owner cabinet
Sign in by email, create a labelled key, and copy it immediately. Intesta stores only its hash and shows the secret once. Send it as a bearer token.
Authorization: Bearer ik_your_key
Anonymous
Entity pages and passports are public. Ask and search currently allow 200 calls per IP in a rolling day.
Agent Free
1,000 units per calendar month. Bulk and watchlist operations are currently enabled.
Agent Pro
100,000 units per calendar month. Recurring online activation is not connected yet.
/usage response reports the selected key only; treat that reporting mismatch as a known limitation.HTTP operations
Start with public reads, add a key for bulk work
The paths below exist in the current FastAPI application and are covered by the project contracts. The machine-readable plan catalog remains at /api/v1/plans.
/api/v1/entities and /api/v1/entities/{domain}/facts: registry list and passport facts.
/api/v1/search?q={query}: search published entities. Query length is 3 to 200 characters.
/api/v1/entities/{domain}/ask: question up to 2,000 characters with channel human or agent.
/api/v1/check-trust/{domain}?purpose=payment: named policy verdict for any domain.
/api/v1/trust-ladder: canonical meaning of A0 to A4.
/api/v1/bulk/entities: key-required batch selection by vertical and minimum level.
/api/v1/watchlist: add domains and read passport-hash changes with a key.
/api/v1/usage: usage for the authenticated API key.
Walkthrough
Search, inspect, then ask
This sequence uses public endpoints and demonstrates the evidence boundary before you add metered bulk operations.
- 1
Search the registry.
GET /api/v1/search?q=Intesta - 2
Inspect signed attestation.
GET /api/v1/attestation/intesta.io, then read facts at/api/v1/entities/intesta.io/facts. - 3
Ask a scoped question.
POST a question andchannel: agentto/api/v1/entities/intesta.io/ask. - 4
Handle the outcome.
Useoutcome,refused, freshness fields and the returned facts. Do not treat HTTP 200 alone as evidence.
curl -sS https://intesta.io/api/v1/entities/intesta.io/ask \
-H 'Content-Type: application/json' \
-d '{"question":"What does this business publish?","channel":"agent"}'
Example refusal response (trimmed)
{
"refused": true,
"outcome": "refused_not_attested",
"reason": "no_matching_fact",
"facts": [],
"answer": null,
"passport_hash": "sha256:…"
}
Errors and refusals
Transport errors and evidence refusals are different
A refusal is a successful contract response saying the passport cannot support the requested answer. Invalid input, missing authentication or exhausted quota are HTTP or MCP errors.
401 / 403
A key is required, the key lacks a capability, or the signed-in account does not own the requested resource.
422
The query, question, level, domain or purpose failed validation.
429
The anonymous allowance, plan units, active-key cap or watchlist cap was exceeded.
refused_not_attested means no matching supported fact; refused_stale means matching evidence was too old to serve. See the typed response contract for all fields and outcomes.Next step
Use the free key before selecting a paid allowance
Connect the remote MCP endpoint or make a public HTTP request, then monitor actual unit use. Paid recurring activation needs the billing integration described on the pricing page.