Verity AI Documentation

A REST API for product authentication. Submit images; receive a structured decision, confidence score, and verifiable certificate.

Overview

Verity sits between your commerce workflows — listing intake, checkout, returns — and provides a product-level trust signal. Returns a decision (authentic, counterfeit, or inconclusive), a confidence score (0.00–1.00), anomaly flags, and a permanent certificate URL. No SDKs required — a single curl call gets you to a decision.

Base URL

https://api.verityai.app/v1

Quickstart

Make your first authentication call in under five minutes.

1. Get your API key

   Log in to the Verity Dashboard → Settings → API Keys. Copy your secret key — it won't be shown again.
2. Authenticate a product

   cURLNode.jsPython

   curl https://api.verityai.app/v1/authenticate \
     -X POST -H "Authorization: Bearer $VERITY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"brand":"ganni","category":"dress","images":["https://cdn.example.com/front.jpg"]}'

   const res = await fetch('https://api.verityai.app/v1/authenticate',{
     method:'POST',
     headers:{'Authorization':`Bearer ${process.env.VERITY_API_KEY}`,'Content-Type':'application/json'},
     body:JSON.stringify({brand:'ganni',category:'dress',images:['https://cdn.example.com/front.jpg']})
   }).then(r=>r.json());
   console.log(res.decision); // "authentic"

   res = requests.post("https://api.verityai.app/v1/authenticate",
     headers={"Authorization":f"Bearer {api_key}"},
     json={"brand":"ganni","category":"dress","images":["https://cdn.example.com/front.jpg"]})
   print(res.json()["decision"]) # "authentic"

3. Read the response

   200 OK · decision: "authentic"2.1s

   {"id":"auth_01j9xkp4mq2n8r7v","decision":"authentic","confidence":0.97,
     "flags":[],"certificate_url":"https://verify.verityai.app/cert/auth_01j9xkp4",
     "processed_at":"2026-02-23T08:22:31Z"}

4. Act on the decision

   Route on decision: approve listings, gate refunds, feed your rules engine. Embed certificate_url in listings or receipts — it's permanent and publicly verifiable.

Authentication

All requests require a Bearer token in the Authorization header. Both verity_sk_live_* (production) and verity_sk_test_* (no quota consumed) key formats are supported.

Authorization: Bearer verity_sk_live_••••••••••••••••

POST /authenticate

The primary endpoint. Submit product images with brand and category metadata; receive a structured decision synchronously.

Request body

Response fields

Example

curl https://api.verityai.app/v1/authenticate \
  -X POST -H "Authorization: Bearer $VERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"ganni","category":"dress","images":["https://cdn.example.com/front.jpg"],"metadata":{"listing_id":"lst_8821"},"threshold":0.85}'

const res = await fetch('https://api.verityai.app/v1/authenticate',{
  method:'POST',
  headers:{'Authorization':`Bearer ${process.env.VERITY_API_KEY}`,'Content-Type':'application/json'},
  body:JSON.stringify({brand:'ganni',category:'dress',images:['https://cdn.example.com/front.jpg'],metadata:{listing_id:'lst_8821'},threshold:0.85})
}).then(r=>r.json());
if(res.decision==='authentic'){/* approve, embed res.certificate_url */}

res = requests.post("https://api.verityai.app/v1/authenticate",
  headers={"Authorization":f"Bearer {api_key}"},
  json={"brand":"ganni","category":"dress","images":["https://cdn.example.com/front.jpg"],
        "metadata":{"listing_id":"lst_8821"},"threshold":0.85}).json()
if res["decision"] == "authentic": db.update_listing(certificate_url=res["certificate_url"])

{"id":"auth_01j9xkp4mq2n8r7v","decision":"authentic","confidence":0.97,
  "flags":[],"brand":"ganni","category":"dress",
  "metadata":{"listing_id":"lst_8821"},
  "certificate_url":"https://verify.verityai.app/cert/auth_01j9xkp4",
  "processed_at":"2026-02-23T08:22:31Z","model_version":"cv-3.1"}

GET /certificate/:id

Retrieve a full authentication record by event ID. Useful for audit trails and dispute resolution. The public certificate page at verify.verityai.app/cert/:id requires no authentication and can be linked directly from listings. For a lightweight boolean validity check, use GET /v1/verify/:id — returns {"valid":true,"decision":"authentic"}.

curl https://api.verityai.app/v1/certificate/auth_01j9xkp4mq2n8r7v \
  -H "Authorization: Bearer $VERITY_API_KEY"

Errors & Status Codes

Errors return JSON with a machine-readable code and human-readable message.

{"error":{"code":"invalid_image_url","message":"Image returned 403.","param":"images[1]"}}

Error codes

Rate Limits

Rate limits apply per API key. Every response includes limit headers.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 986
X-RateLimit-Reset: 1709020800
Retry-After: 60  # only on 429

Shopify Integration

Install Verity into your Shopify store. Authentication fires at listing creation or checkout — no custom development required.

1. Install the Verity app

   Shopify Admin → Apps → App Store → search “Verity AI” → Install.
2. Connect your API key

   Paste your verity_sk_live_* key in app settings. The app validates and displays your quota.
3. Configure your workflow

   Select trigger: product creation, checkout, or return initiation. Set counterfeit action: auto-reject, hold for review, or notify.
4. Embed the trust badge

   Enable from the theme editor. Authenticated listings display a badge linking to the public certificate.

Returns Workflows

Gate refunds by comparing a returned item against its listing. Two calls: one at listing, one at return.

// At listing — store result.id in your OMS
const listing = await authenticate({images:listingImages,brand,category,metadata:{listing_id}});

// At return
const ret = await authenticate({images:returnImages,brand,category,metadata:{order_id,return_id}});

if(ret.confidence >= 0.80 && ret.decision === 'authentic'){
  await oms.approveRefund(order_id);
}else{
  await oms.flagForReview(order_id,{flags:ret.flags});
}

Agentic Commerce NEW

Verity's JSON output is consumable directly by AI agents. The structured response — decision, confidence, certificate URL, flags — is parseable by any LLM without additional tooling. Demonstrated in the Mastercard AI Payment Agent environment.

{"type":"function","function":{
  "name":"authenticate_product",
  "description":"Authenticate a product. Returns decision, confidence, and certificate URL.",
  "parameters":{"type":"object","required":["brand","category","images"],
    "properties":{"brand":{"type":"string"},"category":{"type":"string"},
      "images":{"type":"array","items":{"type":"string","format":"uri"}}}
  }}}

Webhooks BETA

Receive authentication events pushed to your endpoint. Supply a webhook_url in your request, or configure a global endpoint in the dashboard.

Every webhook includes a Verity-Signature header — HMAC-SHA256 signed with your webhook secret.

import crypto from 'crypto';
function verify(rawBody,sig,secret){
  const exp=crypto.createHmac('sha256',secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(exp),Buffer.from(sig));
}

Changelog

Support

Direct engineering support for active integrations. No tickets. No automated responses.