API documentation

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 zod
import { 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.

Want a working agent to fork?
The immigration-paralegal example is ~300 lines of TypeScript that walks Claude through an entire I-130 case using these tools. Ships with a Claude Desktop config and a programmatic Anthropic-SDK entry point.

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.

StepToolPurpose
0capabilitiesGet live enums (languages, doc types, tiers, add-ons). Call once at session start so the agent grounds on real values.
1quoteBinding price + ETA. Returns a quoteId valid for 24h. Free; no order created.
2submitCreate the job. Returns jobId immediately; live keys charge off-session, sandbox is free.
3statusPoll progress. Or subscribe to webhooks and skip polling entirely.
4resultOnce status === ready: fetch the certified PDF URL + the JWS receipt.
verifyPublic, no-auth. Anyone (recipient, agent, end-user) can verify a certificate.
refund30-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.

TransportWhen to useSetup time
REST v1Any 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 SDKTypeScript apps using generateText / streamText / agent loops.~30s

Endpoint cheatsheet

All paths are https://verdacert.com/…. Full reference at /docs/api.

PathPurpose
GET/api/v1/capabilitiesLive enums.
POST/api/v1/quotePrice + ETA. Returns quoteId.
POST/api/v1/submitCreate 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.jsonPublic JWKS. Cache 1h.
POST/api/mcpMCP streamable-HTTP endpoint.
GET/api/v1/openapi.yamlOpenAPI 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.

Where to next

Get instant quotePricing