Quickstart

1. Ground the agent on live enums

curl https://verdacert.com/api/v1/capabilities \
  -H "Authorization: Bearer vc_sandbox_…"

Returns supported languages, document types, speed tiers, add-ons (and whether each is currently available), and the USCIS acceptance guarantee URL. Cacheable for ~1h on your side.

2. Get a binding 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"
  }'

Response carries quoteId, totalCents, an itemized breakdown, promisedDeliveryAt, and expiresAt (24h TTL). Show totalCents / 100 to your end-user; ask for confirmation; then submit.

3. Submit the job

curl -X POST https://verdacert.com/api/v1/submit \
  -H "Authorization: Bearer vc_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId":        "q_aabbccdd_1716480000000_x9k3",
    "idempotencyKey": "demo-order-0001",
    "echoedInput": {
      "sourceLanguage": "fa",
      "useCase":        "uscis",
      "pageCount":      2,
      "speedTier":      "standard"
    },
    "documents": [
      { "url": "https://example.com/birth-cert.pdf" }
    ]
  }'

Returns a jobId immediately. The idempotencyKey is yours to choose; reuse it to safely retry the same submit without creating a duplicate order.

4. Poll until ready

# Sandbox flips through states on a wall clock
# in ~2 minutes; recommend exponential backoff starting at 30s.
curl https://verdacert.com/api/v1/status/<jobId> \
  -H "Authorization: Bearer vc_sandbox_…"

Returns status, progressPercent (0–100), statusDescription, and an events array. Stop polling when status === "ready", or skip polling entirely and use webhooks.

5. Fetch the certified result

curl https://verdacert.com/api/v1/result/<jobId> \
  -H "Authorization: Bearer vc_sandbox_…"

Returns the certified PDF URL, the certificate metadata (issuer, translator, public verify URL), and a compact JWS you can verify against the live JWKS without calling us.

6. Verify the certificate (public, no auth)

curl https://verdacert.com/api/v1/verify/<certificateId>

The verification endpoint never requires a key. That's the design: a USCIS reviewer, an opposing lawyer, or a university registrar can verify a Verdacert receipt with zero setup. Full walkthrough at /docs/certificates.

Install

pnpm add @verdacert/ai-sdk-tools ai zod
# or: npm i @verdacert/ai-sdk-tools ai zod

Use

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:
    "I have a 3-page Farsi birth certificate at " +
    "https://example.com/cert.pdf that I need certified " +
    "for USCIS. Quote it, submit it, poll until ready, " +
    "and give me back the certified URL.",
});

console.log(text);

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "verdacert": {
      "url": "https://verdacert.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vc_sandbox_…"
      }
    }
  }
}

Cursor

Settings → MCP → Add new MCP server. Same JSON as above.

Any HTTP client (raw JSON-RPC)

curl https://verdacert.com/api/mcp \
  -H 'Authorization: Bearer vc_sandbox_…' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id":      1,
    "method":  "tools/list",
    "params":  {}
  }'