API Reference

Base URL: https://adzhi.co.uk/api · Version: v1 · API plan required

Overview

The AdZhi API provides programmatic access to acoustic analysis of video advertisements. Submit a video file or URL, poll for completion, and retrieve a full analysis result in JSON.

API access requires the API plan (£99/month) or an Enterprise plan. Start by creating an account and upgrading at /pricing.

Authentication

All API requests require a Bearer token in the Authorization header. Obtain your token by calling the login endpoint.

Manage your API keys →

Get a token

# POST /api/auth/login
curl -X POST https://adzhi.co.uk/api/auth/login   -H "Content-Type: application/json"   -d '{"email": "you@example.com", "password": "..."}'

# Response
{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Tokens expire after 24 hours. Store them securely — do not embed in client-side code.

Errors

Code	Meaning
`401`	Missing or invalid token
`403`	API plan not active, or plan limit reached
`413`	File too large (max 500MB)
`422`	Validation error — check request body
`503`	Service temporarily unavailable — retry after 30s

POST /api/jobs/upload

POST Upload a video file for analysis. Accepted formats: mp4, mov, mkv, avi, webm. Max size: 500MB.

curl -X POST https://adzhi.co.uk/api/jobs/upload   -H "Authorization: Bearer $TOKEN"   -F "files=@skincare-ad.mp4"

# Response — job queued
{
  "job_ids": ["3f8a2b1c-..."]
}

POST /api/jobs/from-url

POST Submit a YouTube or public video URL for analysis.

curl -X POST https://adzhi.co.uk/api/jobs/from-url   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"url": "https://youtube.com/watch?v=...", "label": "Skincare UGC v3"}'

# Response
{"job_id": "3f8a2b1c-..."}

GET /api/jobs/{job_id}/status

GET Poll for job completion. Analysis typically completes in 2–4 minutes.

curl https://adzhi.co.uk/api/jobs/3f8a2b1c-.../status   -H "Authorization: Bearer $TOKEN"

# Response — pending
{"status": "processing", "stage": "acoustic_analysis"}

# Response — complete
{"status": "finished", "job_id": "3f8a2b1c-..."}

GET /api/jobs/{job_id}/events

GET Server-Sent Events (SSE) stream for real-time progress. Pass the token as a query parameter — EventSource cannot set headers.

const es = new EventSource(
  `/api/jobs/${jobId}/events?token=${encodeURIComponent(token)}`
);

es.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.status      — "queued" | "started" | "finished" | "failed"
  // msg.progress     — 0.0–1.0 float
  // msg.stage        — human-readable current stage
  // msg.partial_result — transcript + acoustics before full analysis (stage 1: "acoustics", stage 2: "nlp")
  if (msg.status === "finished" || msg.event === "close") es.close();
};

The stream closes automatically at terminal status or after a safety timeout. Use partial_result to progressively render transcript and Voice IQ tiles before the full result is ready.

GET /api/jobs

GET List all analyses in your account.

curl "https://adzhi.co.uk/api/jobs?limit=20&offset=0"   -H "Authorization: Bearer $TOKEN"

GET /api/insights/benchmarks/{job_id}

GET Benchmark percentile rankings for this analysis against your account cohort and the global fleet (users who have opted in to data sharing). Returns null fields when fewer than 10 comparable jobs exist.

curl "https://adzhi.co.uk/api/insights/benchmarks/${JOB_ID}"   -H "Authorization: Bearer $TOKEN"

# Response
{
  "adzhi_score_pct": 72,       // percentile vs similar ads
  "hook_score_pct":  88,
  "voice_iq_pct":   61,
  "cohort": "skincare · meta",  // inferred cohort
  "n": 47                     // number of ads in cohort
}

Result schema

Retrieve the full analysis result by fetching job details:

curl https://adzhi.co.uk/api/jobs/3f8a2b1c-...   -H "Authorization: Bearer $TOKEN"

Key top-level fields in the result:

Field	Type	Description
`adzhi_score`	object	Composite score (0–100), grade, biggest lever, component breakdown
`acoustics`	object	Voice IQ, pitch trajectory, energy curve, disfluency, WPM, rhythm
`act_structure`	object	Hook analysis (score, type, critique), persuasion arc, LLM rewrites
`intelligence`	object	Misalignments (7 types, timestamped), attention curve, persuasion DNA
`proprietary_metrics`	object	8 named metrics: Voice IQ™, CTA Momentum™, Hook Decay Rate™, etc.
`cross_signal_alignment`	object	Silent viewer score, dual-channel CTA, audio-visual sync
`predictions`	object	Thumb-stop probability, CTR estimate, fatigue velocity, fragility
`missed_opportunities`	array	Absent signals that would predictably improve performance — each item has `title`, `insight`, `fix`, `estimated_impact`
`nlp`	object	CTAs, urgency phrases, social proof, benefit phrases, readability
`visual`	object	Caption analysis (timed, classified), face visibility, scene cuts, motion
`api_cost`	object	Per-analysis Anthropic token usage — see API cost

API cost transparency

Every analysis result includes an api_cost object so you can see exactly what each analysis consumed in Claude API calls. This is intended for operators building on top of AdZhi, not end-users.

{
  "claude_calls":        8,
  "total_input_tokens":  14200,
  "total_output_tokens": 3100,
  "total_cost_usd":      0.089150,
  "total_cost_gbp":      0.070429
}

Key metric ranges

Metric	Range	Good threshold
AdZhi Score	0–100	≥ 70
Voice IQ™	0–100	≥ 65
CTA Momentum™	0–100	≥ 70
Hook score	0–10	≥ 7.0
Hook Decay Rate™	0–100	≥ 60
Silent viewer score	0–100	≥ 50
Thumb-stop probability	0–1	≥ 0.55

Rate limits

API requests are rate-limited at 60 requests per minute per account. Analysis submissions are limited by your plan's monthly analysis quota. The API plan includes 500 analyses per month. Exceeding the analysis limit returns 403 with detail: "Plan limit reached".

Questions? Email hello@adzhi.co.uk or upgrade to API plan →