API Documentation

Everything you need to integrate expert verification into your AI pipeline.

Quick Start

Get your first expert review in 3 steps:

1. Get your API key

bash

curl -X POST https://withev.com/api/v1/clients \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Your Company",
    "contactName": "Your Name",
    "email": "you@company.com"
  }'

# Response
{
  "id": "a1b2c3d4",
  "api_key": "ev_live_abc123...",
  "message": "Save your API key — it won't be shown again."
}

2. Add funds to your account

bash

curl -X POST https://withev.com/api/v1/balance \
  -H "Authorization: Bearer ev_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000 }'  # $100.00 in cents

3. Submit your first review

bash

curl -X POST https://withev.com/api/v1/verify \
  -H "Authorization: Bearer ev_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "output": "BPC-157 is safe to take alongside metformin.",
    "domain": "healthcare",
    "specialty": "pharmacology",
    "urgency": "standard"
  }'

# Response
{
  "id": "r_x1y2z3",
  "status": "pending",
  "urgency": "standard",
  "sla": "< 24 hours",
  "cost": "$8.00",
  "expert_available": true,
  "poll_url": "/api/v1/reviews/r_x1y2z3"
}

4. Poll for the result

bash

curl https://withev.com/api/v1/reviews/r_x1y2z3 \
  -H "Authorization: Bearer ev_live_abc123..."

# Response (when completed)
{
  "id": "r_x1y2z3",
  "status": "completed",
  "domain": "healthcare",
  "urgency": "standard",
  "result": {
    "score": 0.7,
    "verdict": "partially_correct",
    "correction": "Generally safe but limited human data. Monitor blood glucose more frequently as BPC-157 may affect insulin sensitivity.",
    "confidence": 0.85
  },
  "completed_at": "2026-04-22T14:32:00Z"
}

Authentication

All API requests require a Bearer token in the Authorization header:

http

Authorization: Bearer ev_live_your_api_key_here

Your API key is returned when you create a client account. Store it securely — it provides full access to your account.

Submit a Review

POST/api/v1/verifySubmit an AI output for expert verification

This is the core endpoint. Send an AI-generated output and get it reviewed by a credentialed domain expert.

Request body

Field	Type	Required	Description
`output`	string	Yes	The AI-generated text to verify
`domain`	string	Yes	Domain for expert matching (see Domains)
`urgency`	string	No	Response time tier: standard, fast, realtime, critical. Default: standard
`specialty`	string	No	Sub-specialty for better matching (e.g. "pharmacology", "cardiology")
`context`	string	No	Additional context about what the AI was asked

javascript

// Node.js example
const response = await fetch("https://withev.com/api/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ev_live_abc123...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    output: "Testosterone therapy has no cardiovascular risks.",
    domain: "healthcare",
    specialty: "endocrinology",
    urgency: "realtime",
    context: "Patient asked about TRT safety"
  })
});

const data = await response.json();
console.log(data.id);       // "r_x1y2z3"
console.log(data.status);   // "pending"
console.log(data.cost);     // "$30.00"

Note: Your account balance is deducted immediately when a review is created. If the review expires without being completed, the charge is refunded.

Get Results

GET/api/v1/reviews/:idGet a single review by ID

Poll this endpoint to check if your review has been completed. Or use webhooks for real-time notifications.

bash

curl https://withev.com/api/v1/reviews/r_x1y2z3 \
  -H "Authorization: Bearer ev_live_abc123..."

Review statuses

`pending`	Waiting for an expert to claim it
`claimed`	An expert is reviewing it
`completed`	Expert has submitted their review — result is available
`expired`	No expert completed the review within the SLA window

Result object

`score`	number	0-1 accuracy score
`verdict`	string	correct, partially_correct, incorrect, unsafe, or needs_context
`correction`	string \| null	What the AI should have said (if wrong)
`notes`	string \| null	Additional context from the expert
`confidence`	number	0-1 expert confidence in their review

GET/api/v1/reviewsList all your reviews

Query parameters:

`status`	Filter by status (pending, claimed, completed, expired)
`domain`	Filter by domain
`limit`	Max results (default 50)

Balance

GET/api/v1/balanceCheck your current balance

bash

curl https://withev.com/api/v1/balance \
  -H "Authorization: Bearer ev_live_abc123..."

# Response
{
  "balance": 8500,
  "balance_formatted": "$85.00",
  "review_count": 15
}

POST/api/v1/balanceAdd funds (amount in cents)

bash

curl -X POST https://withev.com/api/v1/balance \
  -H "Authorization: Bearer ev_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000 }'  # $500.00

Webhooks

Get notified instantly when a review is completed instead of polling.

POST/api/v1/webhooksCreate a webhook

bash

curl -X POST https://withev.com/api/v1/webhooks \
  -H "Authorization: Bearer ev_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ev",
    "events": ["review.completed"]
  }'

# Response
{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/ev",
  "events": ["review.completed"],
  "secret": "whsec_xyz789...",
  "message": "Save your webhook secret — it won't be shown again."
}

Webhook payload

When a review is completed, we POST to your URL:

json

{
  "event": "review.completed",
  "review_id": "r_x1y2z3",
  "domain": "healthcare",
  "urgency": "realtime",
  "result": {
    "score": 0.7,
    "verdict": "partially_correct",
    "correction": "Monitor blood glucose more frequently.",
    "confidence": 0.85
  },
  "timestamp": "2026-04-22T14:32:00Z"
}

Headers we send

`X-Webhook-Secret`	Your webhook secret for verification
`X-Event-Type`	The event type (e.g. review.completed)
`Content-Type`	application/json

GET/api/v1/webhooksList your webhooks

DELETE/api/v1/webhooksDelete a webhook

API Keys

POST/api/v1/keysRotate your API key

Generates a new API key and invalidates the old one immediately. Use this if your key is compromised.

bash

curl -X POST https://withev.com/api/v1/keys \
  -H "Authorization: Bearer ev_live_old_key..."

# Response
{
  "api_key": "ev_live_new_key...",
  "message": "Old key is now invalid."
}

Usage Stats

GET/api/v1/usageGet your usage statistics

bash

curl https://withev.com/api/v1/usage \
  -H "Authorization: Bearer ev_live_abc123..."

# Response
{
  "balance": 8500,
  "balance_formatted": "$85.00",
  "total_reviews": 142,
  "pending_reviews": 3,
  "total_spent": 215000,
  "total_spent_formatted": "$2,150.00",
  "today": 12,
  "this_week": 47,
  "this_month": 142,
  "avg_response_time_seconds": 187,
  "by_domain": { "healthcare": 89, "legal": 31, "finance": 22 },
  "by_urgency": { "standard": 60, "fast": 45, "realtime": 30, "critical": 7 }
}

Domains

Pass one of these values as the domain field:

healthcarelegalfinanceinsurancepharmamedical_deviceshreducationhousingimmigrationbiometricslaw_enforcementcritical_infrastructurefinancial_advisorycomplianceengineeringcybergeneral

Urgency Tiers

Tier	SLA	Cost	Best for
`standard`	< 24 hours	$8	Batch verification, non-urgent audits
`fast`	< 1 hour	$15	Same-day verification, production reviews
`realtime`	< 5 minutes	$30	Live pipelines, real-time checks
`critical`	< 2 minutes	$75	Highest priority, dual-expert review

Errors

All errors return a JSON object with an error field:

json

{ "error": "unauthorized", "message": "Include your API key as: Authorization: Bearer ev_live_..." }

Status	Error	Meaning
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient balance
`404`	Not Found	Review or resource not found
`429`	Rate Limited	Too many requests (max 60/minute)
`500`	Server Error	Something went wrong on our end

Ready to integrate?

Get your API key and start verifying AI outputs in minutes.

Get API access