API reference

Four endpoints under /api/v1, all bearer-auth. Mint a token in the quickstart.

StableAvailable since v0.3.0Bearer auth required

POST/api/v1/analyses10 / min / token

Submit an ad URL

Synchronous URL validation, then a 1-credit charge and a worker job. The response carries the new analysis id straight away. If the same normalized URL has been analyzed before, you get a cache hit with status='done' in the same response.

Request body

urlrequired string Full Meta or TikTok Ad Library URL.

Response

`id`	uuid	Analysis id for subsequent GETs.
`status`	enum	`queued` (worker will process), `done` (cache hit).
`cached`	boolean	Present and true when status=done from cache.
`estimatedSeconds`	integer	~90 for queued.
`links.self`	string	Path to GET the analysis.

Status codes

201	Queued (new analysis, worker will run)
200	Done (cache hit — no worker run)
400	invalid_url, missing_url, invalid_body
401	unauthorized
402	insufficient_credits
429	rate_limited

Example

bash

curl -X POST https://adrevila.com/api/v1/analyses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.facebook.com/ads/library/?id=971390442080128"}'

GET/api/v1/analyses60 / min / token

List analyses (paginated)

Returns the token-user's completed analyses, newest first. Failed and in-progress rows are excluded.

Query params

`page`	integer	Default 1, max 100000.
`pageSize`	integer	Default 25, max 100.

Response

`data[].id`	uuid	Analysis id.
`data[].pageName`	string?	Page that ran the ad.
`data[].adId`	string?	Library id.
`data[].source`	enum	`web` or `api`.
`data[].score`	object?	`{ value: 0–100, grade: "A+"…"F" }` when present.
`data[].summary`	string?	First-paragraph summary.
`data[].completedAt`	iso8601	When the worker finished.
`pagination.total`	integer	Total matching analyses.
`pagination.totalPages`	integer	Derived from total and pageSize.

Status codes

200	OK
401	unauthorized
429	rate_limited

Example

bash

curl -H "Authorization: Bearer $TOKEN" \
  "https://adrevila.com/api/v1/analyses?page=1&pageSize=10"

GET/api/v1/analyses/{id}120 / min / token

Fetch one analysis

Returns the analysis. Format is negotiated via the Accept header (see below). JSON is the default.

Path params

id uuid Returned from POST submit.

Headers

`application/json` (default), `text/markdown`, or `application/pdf`.

Response

`id`	uuid
`status`	enum	`queued`, `fetching`, `composing`, `done`, `failed`.
`source`	enum	`web` or `api`.
`report`	object?	Full report when status=done; null otherwise.
`currentStep`	string?	Human-readable step when not done.
`errorMessage`	string?	When status=failed.

Status codes

200	OK
400	not_acceptable (unsupported Accept)
401	unauthorized
403	forbidden (different user owns this id)
404	not_found
429	rate_limited

Example

bash

# JSON
curl -H "Authorization: Bearer $TOKEN" https://adrevila.com/api/v1/analyses/$ID

# Markdown
curl -H "Authorization: Bearer $TOKEN" -H "Accept: text/markdown" \
  https://adrevila.com/api/v1/analyses/$ID

# PDF
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/pdf" \
  https://adrevila.com/api/v1/analyses/$ID -o report.pdf

GET/api/v1/credits120 / min / token

Get credit balance

Returns the current credit balance and the lifetime total purchased. Cheap and safe to poll — agents typically call it before a submit to warn the user about an incoming 402.

Response

`balance`	integer	Current credit balance.
`lifetimePurchased`	integer	Sum of all positive refill deltas across the account.

Status codes

200	OK
401	unauthorized
429	rate_limited

Example

bash

curl -H "Authorization: Bearer $TOKEN" https://adrevila.com/api/v1/credits
# → { "balance": 12, "lifetimePurchased": 41 }