Adspy API

At a glance

Base URL

https://www.adspy.sh/api/v1

Format

JSON, snake_case; errors as RFC 9457 problem details

Authentication

Bearer API key, managed by your organization

Description

OpenAPI 3.1 at adspy.sh/openapi.json

Access

Adspy Enterprise; Instagram is not available in the API

A first request

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"])

The Quickstart takes it from there: a brand's creatives, then its Full Analysis.

What it covers

Every route, parameter and field is in the reference, generated from the OpenAPI 3.1 description at adspy.sh/openapi.json.

Guides

• Quickstart: From an API key to a brand's creatives and its Full Analysis in four requests.
• Authentication and keys: One header, keys your organization manages, and permissions you can narrow.
• Pagination: Lists page with an opaque cursor: send it back with the same filters.
• Rate limits: Limits are set in your Enterprise contract and announced on every answer.
• Idempotency: One key per new request, the same key for its retries.
• Jobs: fetches and exports: Collections and exports answer 202 with a job; read the job until it is done.
• Media links: Media fields hold signed links: use them directly, refresh them by reading the record again.
• Data model: Public evidence about brands' ads and organic posts, in stable snake_case fields.
• Instagram is not available in the API: Instagram accounts and posts stay out of the API. Meta ads, including those on Instagram placements, stay in.
• Changelog: What changed in the API, newest first.
• Security: How keys and requests are protected, and how to reach us about a vulnerability.
• Errors: the problem format and every error code.