// DOCS · API REFERENCE
REST API.
Production base URL: https://api.entit.ai. POST /v1/jobs is paid via x402; GET /v1/jobs/{jobId} is free and rate-limited only by Retry-After.
// x402 PAYMENT
Include a valid X-Payment header on POST /v1/jobs. The first request without payment receives a 402 Payment Required response with accept options for Base and Solana mainnet (same price). See x402.org for client integration details.
Submit a video URL in the JSON body as {"url": "..."} with optional "format" (24 workflow templates — see catalog below). New jobs return 202 with pollUrl. Cache hits return 200 with status success and result inline. Caches are per format — same URL with a different format is a new paid analysis.
curl -X POST https://api.entit.ai/v1/jobs \
-H "Content-Type: application/json" \
-H "X-Payment: <x402-payment-header>" \
-d '{"url": "https://www.tiktok.com/@creator/video/1234567890"}'// RESPONSE · 202 · NEW JOB
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "pending",
"pollUrl": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}// RESPONSE · 200 · CACHED (status: success with inline result)
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"result": {
"platform": "tiktok",
"url": "https://www.tiktok.com/@janecreates/video/7123456789",
"title": "How I grew my account in 30 days",
"author": "Jane Creator",
"authorHandle": "@janecreates",
"transcription": "Here's how I grew my account in 30 days...",
"language": "en",
"onScreenText": "Day 1 · Follow for more",
"visualDescription": "Creator speaking to camera in a home office, cuts to screen recording of analytics dashboard.",
"scenes": [
{
"timestamp": "0:00",
"description": "Talking head, direct to camera"
},
{
"timestamp": "0:08",
"description": "Screen recording of analytics dashboard"
}
],
"processedAt": "2026-05-20T12:34:56Z"
}
}// WORKFLOW FORMATS
Add an optional format field to the request body to swap the default VideoAnalysis result for a typed workflow shape. Same price as the default analysis; caches are isolated per format (same URL with a different format is a new paid job). Responses echo format on every status.
// ALL FORMAT SLUGS · CLOSED ENUM
- Brand: content-screening, creator-brief
- Food: recipe
- Content: tutorial-guide, quote-highlights
- E-commerce: product-tagging, shop-the-look, review-summary
- Health: workout-plan, health-claims
- Education: flashcards, curriculum-tags, language-learning
- News: ugc-verification, breaking-news-signal, eyewitness-timeline
- Music: song-context, lyric-hook, sound-trend
- Sports: technique-analysis, highlight-reel, scouting-report
- Travel: destination-guide, restaurant-discovery
Field reference for typed responses: response schema. Natural-language intents: agent guide / llms.txt.
// REQUEST · POST /v1/jobs WITH FORMAT
curl -X POST https://api.entit.ai/v1/jobs \
-H "Content-Type: application/json" \
-H "X-Payment: <x402-payment-header>" \
-d '{
"url": "https://www.instagram.com/reel/CzABCdef123/",
"format": "recipe"
}'// EXAMPLE 200 RESPONSES · CACHE HIT (typed result; echoes format)
content-screening
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"format": "content-screening",
"result": {
"safe": true,
"riskLevel": "low",
"flags": [],
"summary": "Talking-head creator tips video with no violence, nudity, or substance use. Mild competitive language only.",
"recommendation": "approve",
"adPlacement": {
"suitable": true,
"riskLevel": "low",
"categories": [
"family_friendly"
],
"blocklistMatches": [],
"notes": "Suitable for broad programmatic placement."
}
}
}creator-brief
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"format": "creator-brief",
"result": {
"hook": "I grew 50k followers in 30 days without paid ads.",
"angle": "Organic growth through consistent short-form hooks",
"summary": "Creator walks through a three-step content system: hook formula, posting cadence, and analytics review.",
"keyMoments": [
{
"timestamp": "0:03",
"note": "States the 30-day growth claim"
},
{
"timestamp": "0:22",
"note": "Shows analytics dashboard spike"
}
],
"cta": "Follow for the full playbook",
"transcriptExcerpt": "Here's how I grew my account in 30 days without spending on ads.",
"vetting": {
"contentThemes": [
"creator growth",
"social media"
],
"tone": "energetic, instructional",
"audienceFit": "aspiring creators and marketers",
"brandRiskFlags": [],
"partnershipRecommendation": "approve"
}
}
}recipe
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "CzABCdef123",
"status": "success",
"format": "recipe",
"result": {
"title": "30-second pasta carbonara",
"error": null,
"ingredients": [
{
"item": "spaghetti",
"amount": "200",
"unit": "g"
},
{
"item": "guanciale",
"amount": "100",
"unit": "g"
},
{
"item": "egg yolks",
"amount": "3",
"unit": null
},
{
"item": "pecorino",
"amount": "50",
"unit": "g"
}
],
"instructions": [
{
"step": 1,
"text": "Boil pasta in salted water until al dente."
},
{
"step": 2,
"text": "Crisp guanciale in a pan; reserve fat."
},
{
"step": 3,
"text": "Toss hot pasta with egg-pecorino mixture off heat."
}
],
"metadata": {
"prepTime": "10 minutes",
"cookTime": "15 minutes",
"temperature": {
"value": null,
"unit": "C",
"fanAdjusted": false
},
"yield": "2 servings",
"mealType": "dinner",
"dishType": "main",
"cuisine": "Italian",
"dietaryPreferences": null,
"cookingMethod": "stovetop",
"isQuickAndEasy": true
}
}
}quote-highlights
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"format": "quote-highlights",
"result": {
"highlights": [
{
"timestamp": "0:12",
"quote": "Consistency beats virality every single time.",
"context": "Creator advice on posting cadence",
"shareability": "high"
}
],
"summary": "Motivational creator advice with one highly quotable line."
}
}workout-plan
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"format": "workout-plan",
"result": {
"title": "10-minute HIIT finisher",
"exercises": [
{
"name": "Jump squats",
"sets": "3",
"reps": "15",
"rest": "30s",
"notes": "Land softly"
},
{
"name": "Mountain climbers",
"sets": "3",
"reps": "40s",
"rest": "30s",
"notes": ""
}
]
}
}Error responses listed on the errors page.
Poll job status. Server returns Retry-After: 5 while status is pending or processing. result is populated when status: success.
curl https://api.entit.ai/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890// 200 · PENDING
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "pending"
}// 200 · PROCESSING
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "processing"
}// 200 · SUCCESS
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"videoId": "7123456789",
"status": "success",
"result": {
"platform": "tiktok",
"url": "https://www.tiktok.com/@janecreates/video/7123456789",
"title": "How I grew my account in 30 days",
"author": "Jane Creator",
"authorHandle": "@janecreates",
"transcription": "Here's how I grew my account in 30 days...",
"language": "en",
"onScreenText": "Day 1 · Follow for more",
"visualDescription": "Creator speaking to camera in a home office, cuts to screen recording of analytics dashboard.",
"scenes": [
{
"timestamp": "0:00",
"description": "Talking head, direct to camera"
},
{
"timestamp": "0:08",
"description": "Screen recording of analytics dashboard"
}
],
"processedAt": "2026-05-20T12:34:56Z"
}
}Health check endpoint. Returns 200 with a JSON status payload.
curl https://api.entit.ai/healthz{
"status": "ok"
}