AdnovaDocs
Inspiration

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.tags input.
  • 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) or inspirationSavedAdId (saved), and find similar ads.

Typical flow

  1. Search the library. Search saved ads returns ads as { data, metadata }; each ad carries an inspirationSavedAdId.
  2. Open one ad. Get a saved ad by inspirationSavedAdId.
  3. Explore cross-brand. Discover ads (v2) returns ads carrying an inspirationAdId plus per-ad insights; page with the opaque nextCursor. The v1 Discover ads endpoint is deprecated but keeps working.
  4. Drill into an ad. Get an ad by inspirationAdId, or Get similar ads.
  5. 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_ID

x-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 period

When 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/limit with metadata.totalCount; Discover uses an opaque forward-only nextCursor.
  • 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.