Public API - Docs

The Fovea REST API: list and search creatives, read collections and products, and pull Meta ads performance for one workspace.

Base URL: https://api.foveahq.com/api/v1/public. Authenticate every request with an API key: Authorization: Bearer fov_.... The key decides the workspace; there is no workspace parameter.

The interactive reference (try requests in the browser) lives at api.foveahq.com/api/v1/public/docs, and the OpenAPI document at /api/v1/public/openapi.json.

Endpoints

Method + path	Scope	What it returns
`GET /me`	read	The key's workspace, scopes, role and `revenue_visible`
`GET /assets?q=&tag=&media_type=&limit=&offset=`	read	Creatives, newest first. `q` matches name, description, hook, angle, style, creator, OCR text, transcript and product; every word must match. `tag` repeats. `limit` up to 100.
`GET /assets/{id}`	read	One creative: tags, AI analysis, OCR and transcript excerpt, linked products, linked Meta ads, collections, all-time performance
`GET /assets/top?metric=&days=&date_from=&date_to=&limit=`	read	Creatives ranked by `spend`, `roas`, `ctr`, `impressions` or `purchases` from their linked Meta ads
`GET /collections?q=&limit=`	read	Collections with asset counts
`POST /collections`	write	Create a collection: `{"name", "description"?, "asset_ids"?}`
`POST /collections/{id}/assets`	write	Add assets: `{"asset_ids": [...]}`
`GET /products?q=&limit=&offset=`	read	Products from your Shopify catalog
`GET /products/{id or handle}`	read	A product and its creatives, best sellers first
`GET /ads/summary?days=&date_from=&date_to=&ad_id=&limit=`	read	Account totals and top ads for a window, or one ad's window, lifetime and daily numbers

Spend, revenue, purchases and ROAS appear only for keys with the Money scope; otherwise those keys are absent from the response and revenue_visible is false.

Example

curl "https://api.foveahq.com/api/v1/public/assets/top?metric=roas&days=30&limit=5" \
  -H "Authorization: Bearer fov_your_key"

{
  "metric_used": "roas",
  "window": {"from": "2026-09-22", "to": "2026-10-21"},
  "revenue_visible": true,
  "count": 5,
  "creatives": [
    {"id": "8f2c...", "name": "UGC hook v3", "media_type": "video", "tags": ["ugc"],
     "impressions": 48210, "clicks": 1290, "ctr": 0.0268,
     "spend": 1840.5, "purchases": 61, "revenue": 7302.0, "roas": 3.97}
  ]
}

Errors

Errors use {"detail": ...}, with a code where your code should branch:

Status	Code	Meaning
401	`invalid_api_key`	Missing, unknown, revoked or expired key, or its creator left the workspace
403	`insufficient_scope`	The key lacks the scope (or its creator's role lacks the permission)
403	`upgrade_required`	The workspace is not on a paid plan
404	-	Not found in this workspace (an id from another workspace looks the same)
429	`rate_limited`	Over 120 requests a minute; wait `Retry-After` seconds