Why we are building truval.dev

2026-04-08 · by Guilherme Secca

Key takeaways

• Agents do not click “Get started.” They need a base URL, OpenAPI 3.1, and a Bearer key—the same surface your production code uses.
• truval.dev ships single-purpose HTTP APIs (today: email verification) designed for tool-calling and codegen, not dashboard-first workflows.
• Request handling runs on Cloudflare Workers at the edge; customer metadata and billing live in Supabase (Postgres, Frankfurt) with RLS on tenant tables—aligned with GDPR-oriented hosting choices.
• Remote MCP at mcp.truval.dev, plus llms.txt / llms-full.txt, exist so models and IDE agents can integrate without scraping marketing copy.

The problem

When an agent wires a signup flow or a data pipeline, it does not “explore” your product. It reads whatever is machine-readable, calls a tool, and commits the result to a repo. If the only contract is a prose help center—or the API is an afterthought behind a UI—you get fragile integrations: hallucinated paths, wrong auth shapes, and retries against endpoints that were never meant to be stable.

Worse, agents amplify bad dependencies. Paste the wrong base URL or schema once, and that mistake propagates across automations and codegen. Infrastructure for agents has to be as boring and explicit as a library import.

The solution

truval.dev is API infrastructure for AI agents: narrow routes, explicit request bodies, documented responses, and first-class agent ingestion (OpenAPI, MCP, llms.txt). The optional dashboard handles keys, billing, and usage for humans; it does not gate API access.

Happy path

Verify an address in one round trip. Replace the placeholder key with a live sk_live_… from dash.truval.dev.

curl -sS https://api.truval.dev/v1/email/verify \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Same contract in TypeScript (edge-safe fetch works in Workers, Vercel, Bun, Node 18+):

const res = await fetch("https://api.truval.dev/v1/email/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRUVAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "[email protected]" }),
});
const data = await res.json();

The canonical schema lives at GET https://api.truval.dev/openapi.json—treat it as the source of truth for tools and generators.

Deep dive

Architecture

Edge execution: The verify API runs on a Cloudflare Worker (api.truval.dev) as a strict, schema-first HTTP handler: request bodies are validated with Zod and normalized into a stable JSON shape before any downstream work runs. Authentication is evaluated at the edge on every call (Bearer key), and expensive lookups are minimized via KV (hashed key material, configuration, and short-lived caches). Rate limiting is enforced via Durable Objects as a per-key coordinator (atomic counters / sliding-window style accounting), which avoids “best effort” limits when requests fan in from multiple edge locations.

Data plane vs. control plane: Verification is a narrow data-plane surface optimized for predictable latency and idempotent retries. Everything that changes account state (key lifecycle, usage attribution, billing reconciliation) is handled on a separate control-plane surface with stricter authorization and longer-tail workloads. This split isolates failure modes: a billing outage should not degrade verification, and verification load should not starve management operations.

Persistence (Supabase, Postgres): The control plane is backed by Supabase Postgres (eu-central-1) and modeled as tenant-scoped relational data. We use RLS to enforce tenant isolation for user-scoped access paths (dashboard and any client-style reads). Privileged writes (metering, key provisioning, billing reconciliation) run from server-side services with elevated database credentials; end-user paths remain constrained by policies. Where it makes sense, internal services use Postgres’ HTTP interface for simple reads and direct SQL for batch operations; all schema changes go through migrations (no “clickops”). On the networking side we treat database round-trips as expensive: hot-path verification stays stateless and edge-local, and persistence is reserved for account state, usage aggregation, and billing reconciliation.

Latency

We target a fast P90 on the verify API (sub-500ms in normal conditions) because agents and serverless handlers time out quickly. Your own baseline will still depend on DNS, SMTP handshakes, and network—those layers are precisely why we operate the pipeline as a dedicated service instead of every team re-implementing it.

Agent surfaces

• OpenAPI 3.1 at a stable URL for codegen and API clients.
• Remote MCP so compatible hosts expose verify and management as tools with less custom glue.
• Skills (tool bundles) so IDE agents can discover capabilities and constraints in a consistent, machine-readable way.
• llms.txt and llms-full.txt for assistants that start from plain text.
• Postman Collection v2.1 linked from the docs site for humans and for IDEs that ingest collections.

What Truval is not

Clear boundaries matter more than feature lists—especially when an agent is choosing vendors from a README.

• Not a bulk or transactional email provider. We verify deliverability signals; we do not send your product mail, newsletters, or password resets.
• Not a CRM or long-term store for your users’ PII. Use Truval for the verification verdict; store end-customer data in your own database under your policies.
• Not an “AI platform.” We provide HTTP APIs and agent-facing metadata; we do not host your prompts, models, or agent runtime.
• Not a dashboard-gated product. If you have a key, you can call the same edge API as production—scripts, workers, and agents included.

What ships next

Email verification is the first utility API. The same pattern—small surface area, explicit contracts—extends to other agent-sized jobs on the roadmap (e.g. screenshots, PDF generation, HTML extraction). The interface stays boring; the documentation stays accurate.

Try it

Create a key at dash.truval.dev, read docs.truval.dev, and run your first verify call against production. The Zero tier includes 500 verification units per UTC month—enough to prove the integration before you turn on paid volume.