Skip to content
DEVELOPERS · API AND WEBHOOKS

Script anything the library knows.

A small REST API for scripts, Zapier, Make and n8n, plus signed webhooks when creatives land, finish analysis, or Meta finishes syncing.

Get an API keyAPI reference
Plain HTTPS and JSON, so Zapier, Make, n8n or a cron job can call it

Settings

Integrations

API keys

Let scripts, Zapier, Claude or Cursor read this workspace through the Fovea API and MCP server.

KeyAccessPrefixLast used
Claude CodeReadWritefov_Qm3x8sLp...4m ago
Monday winners reportReadMoneyfov_7TnVb2Kd...2d ago
ZapierReadfov_Hc9wE1rZ...1h ago
Base URL
https://api.foveahq.com/api/v1/public

Event log

Every webhook delivery, with its attempts and response.

EventStatusResponseAttemptsWhen
asset.analyzedDelivered20012m ago
asset.createdDelivered20013m ago
collection.createdDelivered200126m ago
asset.analyzedRetrying503241m ago
ad_sync.completedDelivered20015h ago

“Post our top five creatives to the team every Monday.”

GET /assets/topOne request on a schedule.
FOVEA=https://api.foveahq.com/api/v1/public
$ curl "$FOVEA/assets/top?metric=roas&days=30&limit=5" \
    -H "Authorization: Bearer fov_your_key"

{
  "metric_used": "roas",
  "revenue_visible": true,
  "count": 5,
  "creatives": [
    {"name": "ugc-maya-field40-gift", "media_type": "video",
     "spend": 4210.0, "roas": 3.42, ...},
    ...
  ]
}

Ten endpoints, one key.

Search creatives, rank winners, read products and Meta ads, and build collections. The key decides the workspace.

ReadAssets, top creatives, collections, products and the ads summary.
WriteCreate collections and add assets to them, with the Write scope.
OpenAPIAn interactive reference and the OpenAPI document, public.

Every endpoint, one table.

Base URL api.foveahq.com/api/v1/public. Errors come back as {"detail": ...} with a code to branch on.

GET/meThe key's workspace, scopes, role and revenue_visible.
read
GET/assets?q=&tag=&media_type=&limit=&offset=Search creatives, newest first. Every word of q must match.
read
GET/assets/{id}One creative with analysis, links, collections and performance.
read
GET/assets/top?metric=&days=&limit=Creatives ranked by spend, roas, ctr, impressions or purchases.
read
GET/collections?q=&limit=Collections with asset counts.
read
POST/collectionsCreate a collection: name, description?, asset_ids?.
write
POST/collections/{id}/assetsAdd assets to a collection.
write
GET/products?q=&limit=&offset=Products from your Shopify catalog.
read
GET/products/{id or handle}A product and its creatives, best sellers first.
read
GET/ads/summary?days=&ad_id=&limit=Account totals and top ads, or one ad's numbers.
read
Read the API docsInteractive reference

Event log

Every webhook delivery, with its attempts and response.

EventStatusResponseAttemptsWhen
asset.analyzedDelivered20012m ago
asset.createdDelivered20013m ago
collection.createdDelivered200126m ago
asset.analyzedRetrying503241m ago
ad_sync.completedDelivered20015h ago

Know the moment it happens.

Webhooks post signed JSON to your HTTPS endpoint, retried on failure, with every delivery in the event log. Payloads never carry spend, revenue or ROAS.

SignedHMAC-SHA256 with a timestamp, so you can refuse replays.
Retried30 s, 2 min, 10 min and 1 h, then marked failed.
LoggedStatus, response and attempts for every delivery, with retry.

Four events, signed and retried.

Subscribe an endpoint to any of them. Send a signed test event from Settings at any time.

asset.createdA creative finishes uploading.
asset.analyzedFovi finishes tagging it (also after a re-analysis).
collection.createdA collection is created, from the app, the API or MCP.
ad_sync.completedA Meta ads sync finishes.
Verify a delivery
Fovea-Signature: t=1792606757,v1=5f2b...

expected = hmac_sha256(secret, f"{t}.{raw_body}")
valid    = compare(expected, v1) and now - t < 300
Never money
0 amountsWebhook payloads carry ids, names, tags, analysis status and links. Spend, revenue and ROAS are never in them.

Questions, answered.

Developer docs live at /docs: API keys, public API, webhooks and the MCP server.

Which plans include the API?+

Every paid plan: Starter, Growth, Agency and Enterprise. API keys and webhook endpoints cannot be created during the free trial.

How do I authenticate?+

Send a workspace API key as a bearer token: Authorization: Bearer fov_... The key decides the workspace, so there is no workspace parameter. A key acts with its creator's current role, narrowed by its scopes.

What are the limits?+

120 requests a minute per key, with X-RateLimit-Limit, -Remaining and -Reset on every response and 429 with Retry-After when you go over. Up to 25 active keys and 20 webhook endpoints per workspace.

Can the API upload or tag creatives?+

Not today. The write endpoints create collections and add assets to them; uploads and tagging stay in the app.

How do I verify a webhook?+

Each delivery carries Fovea-Signature with a timestamp and an HMAC-SHA256 of the timestamp and the raw body, signed with your endpoint secret. Reject anything older than five minutes. After you rotate a secret, the old one keeps signing for 24 hours.

What happens when my endpoint is down?+

Fovea retries after 30 seconds, 2 minutes, 10 minutes and 1 hour. After 15 failed deliveries in a row the endpoint is paused; re-enable it from Settings and retry any delivery from the event log.

Your library,
on your terms.

Start a plan, create an API key in Settings, and wire Fovea into the tools you already run.

Start free
  • 14-day free trial
  • No card
  • No ad-spend caps