Skip to navigation
Get started

Migrating to v2

v2 lives at https://api.spyglass.so/v2. Same keys, same credits, same error envelope. v1 still responds at /api/v1, but these docs cover v2 only.

Endpoint map

v1v2
POST /brands/search with type: "BRAND"POST /brands
POST /brands/search with type: "CREATOR"POST /creators
GET /brands/{id}GET /account/{id}
POST /brands/{id}/mediaPOST /media with accountId in the body
POST /brands/indexPOST /account/index
GET /brands/{id}/index-statusGET /account/{id}/index-status
GET /brands/{id}/insightsGET /account/{id}/insights
GET /brands/{id}/campaignsGET /account/{id}/campaigns
GET /brands/{id}/collabsGET /account/{id}/collabs
GET /brands/{id}/landing-pagesGET /account/{id}/landing-pages
POST /commentsPOST /comments (unchanged)
—GET /taxonomies (new)
  • No more mode or type. The endpoint decides brand or creator, and the inputs decide how to search. Precedence is ids > igUsername / tiktokUsername > names > query.
  • brandNames is now names. brandIds is now ids.
  • Username search. Pass igUsername or tiktokUsername to find accounts whose handle contains that text.
  • Different filters. /brands doesn’t accept gender, ageRange, ethnicity or language; /creators does. Both accept location. Sending them to /brands is a 400.
  • Different output. Every row has a type. Creators return profile fields (gender, ageRange, ethnicity, location, language, tiktokEngagementRate) and omit facebookUsername, likes and category.
  • count is now limit. The request field that caps rows is limit, same as /media. Responses still report count, the number of rows returned.
  • sortBy is no longer rejected when you search by query; it is ignored.

Account lookup

GET /account/{id} returns either a brand or a creator. Branch on type.

Media

  • /media takes an optional accountId in the body. Omit it to search the whole corpus, in which case query is required.
  • v1’s semanticSearchQuery is query in v2 (same creative search semantics).
  • Filters are flat. v1’s filters object is gone: put channel, format, status, sortBy, limit and the rest at the top level of the body. The nested ranges are flattened too:
v1 filters.…v2
dateRange.presetdatePreset
dateRange.startDate / endDatestartDate / endDate
daysRun.min / maxminDaysRun / maxDaysRun
viewCount.min / maxminViewCount / maxViewCount
landingPage.value / operatorlandingPage / landingPageMatch
  • userRequest is no longer accepted.
  • Unknown fields return 400 invalid_request.
  • taxonomy on /media and /brands takes path strings from GET /taxonomies (for example Apparel > Footwear > Sneakers). That lookup is free.