Inspiration overview
Search saved ads, browse boards and tags, and discover cross-brand ads.
The Inspiration API exposes the workspace's saved-ads library, its boards and tags, and the cross-brand Discover index — plus single-ad and similar-ad lookups.
What you can do
- Search saved ads — the workspace's saved library, with filters, free-text search, sort, and optional board scope.
- Browse and create boards — drill into boards one level at a time, and create boards and sub-boards.
- Upload inspirations — save your own images and videos into a board (Upload an inspiration).
- List tags — the workspace tags used to populate the
filter.tagsinput. - Discover ads — search the public, cross-brand inspiration index with cursor pagination, plus industry / language reference lists and brand search.
- Fetch a single ad — by
inspirationAdId(cross-brand) orinspirationSavedAdId(saved), and find similar ads.
Typical flow
- Search the library. Search saved ads returns ads as
{ data, metadata }; each ad carries aninspirationSavedAdId. - Open one ad. Get a saved ad by
inspirationSavedAdId. - Explore cross-brand. Discover ads (v2) returns ads carrying an
inspirationAdIdplus per-adinsights; page with the opaquenextCursor. The v1 Discover ads endpoint is deprecated but keeps working. - Drill into an ad. Get an ad by
inspirationAdId, or Get similar ads. - Populate filters. Use List tags, List industries, and List languages.
Auth & request context
Every request needs three headers:
api-key: YOUR_KEY_HERE
x-workspace-id: YOUR_WORKSPACE_ID
x-org-id: YOUR_ORG_IDx-workspace-id and x-org-id are required on every endpoint. The same api-key
works across the Adnova APIs; Inspiration API access is provisioned per
organization — contact Adnova to enable it.
Credits & pricing
Ad-returning endpoints consume ad credits — 1 credit per ad returned. Your organization has an ad-credit allowance for each billing period that scales with your plan and billing term and resets at the start of every period.
Metered endpoints (1 credit per ad in the response): Discover ads (v2), Discover ads (v1, deprecated), Get an ad, Get similar ads, Search saved ads, and Get a saved ad. Everything else — tags, boards, industries, languages, and brand search — is free.
Every metered response reports your live balance in headers:
X-Credit-Cost: 25 # credits this request consumed
X-Credits-Remaining: 875 # credits left in the current period
X-Credits-Limit: 1000 # total credits for the current periodWhen the allowance is exhausted, metered endpoints return 402 with code
API_CREDITS_EXHAUSTED and your usage details; credits refresh automatically at
the start of the next period.
Check your balance any time with Get API credit usage — it's free and never consumes credits.
Conventions
- Pagination — saved ads, boards' ads, and Following Brands use
skip/limitwithmetadata.totalCount; Discover uses an opaque forward-onlynextCursor. - Limits — multi-value filter arrays are capped at 10 items; free-text search is capped at 255 characters.
- Errors —
{ "error": { "code", "message" } }. See Rate limits and versioning.
