# entit.ai API

> Structured analysis API for TikTok, Instagram Reels, and YouTube Shorts. Default VideoAnalysis (transcript, scenes, visual summary) or 24 optional workflow formats (recipe, creator brief, tutorials, e-commerce, health, education, news, music, sports, travel). Async job model: POST /v1/jobs is paid via x402 ($0.10 USDC on Base or Solana mainnet); GET /v1/jobs/{jobId} is free polling.

Website: https://entit.ai
Base URL: https://api.entit.ai

## Endpoints

- [OpenAPI spec](https://api.entit.ai/openapi.json): Machine-readable API specification (OpenAPI 3.1)
- [x402 discovery manifest](https://api.entit.ai/.well-known/x402): Resource fan-out for x402 crawlers
- [Health check](https://api.entit.ai/healthz): Service availability
- [MCP server](https://api.entit.ai/mcp): Streamable HTTP Model Context Protocol endpoint (tools, resources, prompts for agents)

## Documentation

- [API reference](https://entit.ai/docs/api): REST endpoints, request/response examples, and x402 payment flow
- [Response schema](https://entit.ai/docs/response-schema): VideoAnalysis (default) and workflow format shapes
- [Workflow formats](https://entit.ai/docs/api#workflow-formats): Optional `format` on job submit (24 closed templates)
- [Error reference](https://entit.ai/docs/errors): All error codes and messages
- [For agents](https://entit.ai/for-agents): Integration guide for autonomous agents and x402 clients

## Usage

1. POST `https://api.entit.ai/v1/jobs` with JSON `{"url": "<video-url>"}` and optional `"format": "<workflow-format>"`, plus `X-Payment` (x402).
2. On 202, poll `GET /v1/jobs/{jobId}` every 5+ seconds; honor the `Retry-After` header. Polling is free.
3. On 200 (cache hit), `result` is returned inline — no polling needed.

### Workflow formats (optional)

Omit `format` → default `VideoAnalysis` (transcript, scenes, visual summary).

Caches are **per format**: same URL with a different `format` (or generic after a format job) runs a new full analysis and is a new paid submit. Repeat the same URL **and** `format` for a free cache hit.

**Limitations:** Formats analyze a single short-form video. E-commerce formats return `searchQuery` strings, not purchase URLs. Health, news, and verification formats flag claims for review—they do not assert facts are true. Feed-scale monitoring (many videos) is achieved by orchestrating many jobs.

| Vertical | `format` | Purpose |
|----------|----------|---------|
| Brand | `content-screening` | Brand safety, UGC compliance, ad-placement suitability |
| Brand | `creator-brief` | Hooks, angle, key moments, influencer vetting |
| Food | `recipe` | Ingredients and steps from cooking clips |
| Content | `tutorial-guide` | How-to videos → written guide / FAQ |
| Content | `quote-highlights` | Shareable quotes and highlight moments |
| E-commerce | `product-tagging` | Products shown with search queries |
| E-commerce | `shop-the-look` | Fashion items and outfit search queries |
| E-commerce | `review-summary` | Pros/cons from product review videos |
| Health | `workout-plan` | Exercises with sets, reps, rest |
| Health | `health-claims` | Medical claims flagged for fact-checking |
| Education | `flashcards` | Study flashcards from educational content |
| Education | `curriculum-tags` | Subject, difficulty, learning objectives |
| Education | `language-learning` | Phrases, vocabulary, grammar patterns |
| News | `ugc-verification` | Scene/location hints for citizen journalism checks |
| News | `breaking-news-signal` | Newsworthiness signal from one clip |
| News | `eyewitness-timeline` | Structured timeline of factual claims |
| Music | `song-context` | Background music / performance for licensing |
| Music | `lyric-hook` | Lip-sync, hooks, rights notes |
| Music | `sound-trend` | Audio description and viral potential |
| Sports | `technique-analysis` | Coaching cues for technique clips |
| Sports | `highlight-reel` | Action-dense clip timestamps |
| Sports | `scouting-report` | Athlete performance notes for coaches |
| Travel | `destination-guide` | Itinerary, tips, costs from travel vlogs |
| Travel | `restaurant-discovery` | Dishes, prices, atmosphere from food reviews |

### Agent discovery (natural language → format)

Map user intent to `"format": "<slug>"` on POST /v1/jobs:

- "convert a cooking YouTube Short or TikTok to a text recipe" → `recipe`
- "turn a how-to Reel into written steps or documentation" → `tutorial-guide`
- "extract pull quotes from a short-form video for social posts" → `quote-highlights`
- "brand safety check before reposting UGC" → `content-screening`
- "influencer vetting brief with hooks and key moments" → `creator-brief`
- "find products shown in a shopping haul video" → `product-tagging`
- "shop the outfit from a fashion Reel" → `shop-the-look`
- "summarize pros and cons from a product review Short" → `review-summary`
- "build a workout from a fitness TikTok" → `workout-plan`
- "flag medical or wellness claims in a health video" → `health-claims`
- "make flashcards from an educational Short" → `flashcards`
- "tag curriculum subject and difficulty from a lesson clip" → `curriculum-tags`
- "extract vocabulary from a language-learning video" → `language-learning`
- "verify citizen journalism footage location and scene" → `ugc-verification`
- "is this clip breaking news" → `breaking-news-signal`
- "timeline of eyewitness claims from one clip" → `eyewitness-timeline`
- "identify background music for licensing" → `song-context`
- "lip-sync hook and rights notes from a music Short" → `lyric-hook`
- "describe audio and viral trend potential" → `sound-trend`
- "coaching cues from a sports technique video" → `technique-analysis`
- "timestamps for highlight reel moments" → `highlight-reel`
- "scouting report from game footage" → `scouting-report`
- "itinerary and tips from a travel vlog Short" → `destination-guide`
- "restaurant dishes and prices from a food review Reel" → `restaurant-discovery`

Supported platforms: TikTok, Instagram Reels, YouTube Shorts.
Authentication: x402 micropayment per submit call. No API keys or accounts.
Discovery: listed on [agentic.market](https://agentic.market) and the x402 directory.

## Optional

- [Developer docs](https://entit.ai/docs): Documentation index
- [Pricing](https://entit.ai/pricing): Per-call pricing
- [Terms](https://entit.ai/terms): Terms of service
- [Privacy](https://entit.ai/privacy): Privacy policy