Verdacert API
Certified translation as an API for AI agents and partner platforms. Seven tools — quote, submit, status, result, refund, verify, capabilities — mirrored across REST, MCP, and a typed Vercel AI SDK tool catalog. Auth is a single Bearer token. Sandbox tokens are free and exercise the full state machine end-to-end.
60-second setup
Three independent paths, pick whichever fits. Every path uses the same key and hits the same backend — switch later for free.
1. Get a key
Self-serve at verdacert.com/onboarding. Sign in, name your firm, mint a sandbox key. Live keys unlock the moment you add a default payment method — no waitlist, no sales call.
Sandbox keys look like: vc_sandbox_p7q8r… (free, synthetic flow)
Live keys look like: vc_live_abc123… (real orders, real money)2a. Curl path
Health-check capabilities, then quote — that's your full wire test:
# Live enums you can call with
curl https://verdacert.com/api/v1/capabilities \
-H "Authorization: Bearer vc_sandbox_…"
# Binding price + ETA quote
curl -X POST https://verdacert.com/api/v1/quote \
-H "Authorization: Bearer vc_sandbox_…" \
-H "Content-Type: application/json" \
-d '{
"sourceLanguage": "fa",
"useCase": "uscis",
"pageCount": 2,
"speedTier": "standard"
}'2b. Vercel AI SDK path
One import gives any AI SDK call all seven tools, typed and ready:
pnpm add @verdacert/ai-sdk-tools ai zodimport { generateText, stepCountIs } from "ai";
import { createVerdacertTools } from "@verdacert/ai-sdk-tools";
const tools = createVerdacertTools({
apiKey: process.env.VERDACERT_API_KEY!,
});
const { text } = await generateText({
// Routes through Vercel AI Gateway automatically when
// AI_GATEWAY_API_KEY is present (auto-injected on Vercel).
model: "anthropic/claude-sonnet-4",
tools,
stopWhen: stepCountIs(20),
prompt: "Quote a 3-page Farsi birth certificate for USCIS.",
});2c. MCP path (Claude Desktop, Cursor, …)
Drop this into ~/Library/Application Support/Claude/claude_desktop_config.json (or your client's equivalent) and restart:
{
"mcpServers": {
"verdacert": {
"url": "https://verdacert.com/api/mcp",
"headers": { "Authorization": "Bearer vc_sandbox_…" }
}
}
}All seven tools (capabilities, quote, submit, status, result, refund, verify) show up in your client's tool picker immediately.
The mental model
The whole API is the same five-step pipeline regardless of which transport you use. Once you've internalized this, every endpoint slots into place.
| Step | Tool | Purpose |
|---|---|---|
| 0 | capabilities | Get live enums (languages, doc types, tiers, add-ons). Call once at session start so the agent grounds on real values. |
| 1 | quote | Binding price + ETA. Returns a quoteId valid for 24h. Free; no order created. |
| 2 | submit | Create the job. Returns jobId immediately; live keys charge off-session, sandbox is free. |
| 3 | status | Poll progress. Or subscribe to webhooks and skip polling entirely. |
| 4 | result | Once status === ready: fetch the certified PDF URL + the JWS receipt. |
| — | verify | Public, no-auth. Anyone (recipient, agent, end-user) can verify a certificate. |
| — | refund | 30-day window. Full or partial. Idempotency-keyed Stripe-side. |
Transports
Three ways to call the same backend. Use whichever fits your runtime — the contracts are identical.
| Transport | When to use | Setup time |
|---|---|---|
| REST v1 | Any language with HTTP + JSON. Fallback when MCP / AI SDK don't fit. | ~30s |
| MCP (streamable HTTP) | Claude Desktop, Cursor, OpenAI Agent SDK, any MCP client. | ~60s |
| Vercel AI SDK | TypeScript apps using generateText / streamText / agent loops. | ~30s |
Endpoint cheatsheet
All paths are https://verdacert.com/…. Full reference at /docs/api.
| Path | Purpose | |
|---|---|---|
| GET | /api/v1/capabilities | Live enums. |
| POST | /api/v1/quote | Price + ETA. Returns quoteId. |
| POST | /api/v1/submit | Create order. Returns jobId. |
| GET | /api/v1/status/{jobId} | Poll state + progress. |
| GET | /api/v1/result/{jobId} | Artifacts + JWS receipt. |
| POST | /api/v1/refund/{jobId} | Full or partial refund. |
| GET | /api/v1/verify/{certificateId} | Public — no auth. JWS + decoded payload. |
| GET | /.well-known/jwks.json | Public JWKS. Cache 1h. |
| POST | /api/mcp | MCP streamable-HTTP endpoint. |
| GET | /api/v1/openapi.yaml | OpenAPI 3.1 (feed to Stainless / Speakeasy / Postman). |
Browse the docs
Everything you need is one click away from here.
Help & contact
Drop a line to hello@verdacert.com for partnerships, live-mode allow-listing, or rev-share. Include the x-vc-request-id header value from any failed call — we use it to look up the exact request in our logs.
For real-time platform status, see verdacert.com/status.
