# AdRevila

> Ad-analysis API for Meta and TikTok Ad Library URLs. Get a structured
> teardown — score, hook, script, visual, CTA, A/B test hypotheses — in
> JSON, Markdown, or PDF.

## Docs

- [Developer overview](https://adrevila.com/developers)
- [Quickstart](https://adrevila.com/developers/quickstart)
- [API reference](https://adrevila.com/developers/api-reference)
- [Errors](https://adrevila.com/developers/errors)
- [Rate limits](https://adrevila.com/developers/rate-limits)
- [Agents (MCP, OpenAPI)](https://adrevila.com/developers/agents)
- [OpenAPI spec (YAML)](https://adrevila.com/api/v1/openapi.yaml)
- [OpenAPI spec (JSON)](https://adrevila.com/api/v1/openapi.json)

## Endpoints

- POST /api/v1/analyses           Submit a URL; returns id for polling
- GET  /api/v1/analyses           List the user's completed analyses
- GET  /api/v1/analyses/{id}      Fetch one (JSON / Markdown / PDF via Accept header)
- GET  /api/v1/credits            Get current credit balance + lifetime purchased
- POST /api/v1/mcp                Model Context Protocol JSON-RPC endpoint

## Auth

All endpoints require a bearer token. Format: pat_<43-char base64url>.
Get one at /settings → Developers.

## MCP

For agents that speak the Model Context Protocol, point your client at
https://adrevila.com/api/v1/mcp with Authorization: Bearer pat_...
Four tools: analyze_ad, list_analyses, get_analysis, get_credit_balance.

## Report shape

A completed analysis (status=done) returns a Report with:

- score: { value, grade, reasoning, breakdown? } — breakdown carries
  per-section subscores plus an optional coherence bonus and penalties.
- summary: prose paragraph.
- hook / script / visual / cta: { archetype | framework | style | commitment,
  works[], doesntWork[], references[], worksDetail[]?, doesntWorkDetail[]? }
  — *Detail entries add { text, confidence, evidence_source } on phase-21+
  reports; older reports expose only the flat works/doesntWork strings.
- actions: { steal, adapt, skip } — Strategic Playbook items, each
  { title, body }.
- abHypotheses: 2-3 { slot, hypothesis, predictedImpact, falsifiableSignal }
  variant briefs.
- schwartz: { primary, secondary?, reasoning } — awareness-stage label.
  Legacy reports may instead have schwartz.stage.
- references: flat reference slugs. referencesHydrated: { key, name,
  source, blurb } for each slug.

See /api/v1/openapi.yaml for the full machine-readable schema.