Quickstart
From an API key to a brand's creatives and its Full Analysis in four requests.
Updated · API v1
Get a key
The REST API is part of Adspy Enterprise. An owner or admin of your organization creates a key in Adspy, in Settings, then API: a name, a workspace, its permissions (read, actions, export), a lifetime of 30, 90 or 365 days and, if you want, the addresses allowed to use it.
The key is shown once. Keep it in your secret manager or an environment variable, never in code or in a browser. The examples below read it from ADSPY_API_KEY.
export ADSPY_API_KEY="adspy_sk_…"Search a brand
Every request goes to https://www.adspy.sh/api/v1 with the key in the Authorization header. Lists answer with data, has_more and next_cursor.
curl "https://www.adspy.sh/api/v1/brands?query=northstar&limit=5" \
-H "Authorization: Bearer $ADSPY_API_KEY"const response = await fetch(
"https://www.adspy.sh/api/v1/brands?query=northstar&limit=5",
{ headers: { Authorization: `Bearer ${process.env.ADSPY_API_KEY}` } },
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const brand of body.data) console.log(brand.brand_key, brand.name);import os
import requests
response = requests.get(
"https://www.adspy.sh/api/v1/brands",
params={"query": "northstar", "limit": 5},
headers={"Authorization": f"Bearer {os.environ['ADSPY_API_KEY']}"},
timeout=70,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body['code']}: {body['detail']}")
for brand in body["data"]:
print(brand["brand_key"], brand["name"]){
"data": [
{
"brand_key": "northstar",
"name": "Northstar",
"logo_url": "https://www.adspy.sh/media/5b0c…?grant=9f2e…",
"website": "https://northstar.example",
"ad_platforms": ["meta", "google"],
"industry": "Food & Beverage",
"creative_count": 412,
"social": { "platforms": ["tiktok"], "posts": 318 }
}
],
"has_more": false,
"next_cursor": null,
"total": 1,
"social_only_brands": []
}Each brand carries its brand_key: every brand route takes it. Media links such as logo_url are signed and work without the key (see Media links).
Read its creatives
A brand's creatives take the creative search filters: status, format, platform, sort, tags, language, min_days_active and a text query with its scope.
curl "https://www.adspy.sh/api/v1/brands/northstar/creatives?status=active&sort=longest&limit=20" \
-H "Authorization: Bearer $ADSPY_API_KEY"const url = new URL("https://www.adspy.sh/api/v1/brands/northstar/creatives");
url.search = new URLSearchParams({ status: "active", sort: "longest", limit: "20" });
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.ADSPY_API_KEY}` },
});
const { data, has_more, next_cursor } = await response.json();response = requests.get(
"https://www.adspy.sh/api/v1/brands/northstar/creatives",
params={"status": "active", "sort": "longest", "limit": 20},
headers={"Authorization": f"Bearer {os.environ['ADSPY_API_KEY']}"},
timeout=70,
)
page = response.json()Run a Full Analysis
Reports are POST requests when they run work: send an Idempotency-Key with each one, so a retry after a timeout returns the same report instead of running it twice.
curl -X POST "https://www.adspy.sh/api/v1/brands/northstar/full-analysis" \
-H "Authorization: Bearer $ADSPY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"range": "90d"}'const response = await fetch("https://www.adspy.sh/api/v1/brands/northstar/full-analysis", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ADSPY_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({ range: "90d" }),
});
const analysis = await response.json();import uuid
response = requests.post(
"https://www.adspy.sh/api/v1/brands/northstar/full-analysis",
json={"range": "90d"},
headers={
"Authorization": f"Bearer {os.environ['ADSPY_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=70,
)
analysis = response.json()The report is reused for 24 hours. Its numbers come with their n, confidence interval and test; it reads public evidence, never spend or results.
Next
- Authentication and keys: permissions, rotation and the IP allowlist.
- Errors: the problem format and every error code.
- Pagination, Rate limits and Idempotency: what a robust client handles.
- The reference: every route, parameter and field, from the OpenAPI document at adspy.sh/openapi.json.