{"openapi":"3.0.0","paths":{"/v1":{"get":{"description":"Returns a minimal bootstrap payload describing the current Trendtrack Public API version and status.","operationId":"PublicApiController_getApiInfo","parameters":[],"responses":{"200":{"description":"Public API metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiInfoResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"summary":"Get public API metadata","tags":["System"]}},"/v1/health":{"get":{"description":"Returns a lightweight health payload for the public bootstrap mounted under /v1.","operationId":"PublicApiHealthController_checkHealth","parameters":[],"responses":{"200":{"description":"Public bootstrap health snapshot. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHealthResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"summary":"Check public API health","tags":["System"]}},"/v1/system/freshness":{"get":{"description":"Returns the latest ready and latest indexed/scheduled global snapshot dates for public API reach-history data.","operationId":"PublicApiSystemFreshnessController_getFreshness","parameters":[],"responses":{"200":{"description":"Global public API data freshness payload. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiSystemFreshnessResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"summary":"Read public API data freshness","tags":["System"]}},"/v1/me":{"get":{"description":"Returns the workspace, credential, and delegated user context resolved from the provided public API key.","operationId":"PublicApiMeController_getMe","parameters":[],"responses":{"200":{"description":"Resolved public API identity payload. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMeResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Resolve the current API credential","tags":["Identity"]}},"/v1/usage":{"get":{"description":"Returns the current public API billing, included quota, and credit balance snapshot for the authenticated workspace.","operationId":"PublicApiUsageController_getUsage","parameters":[],"responses":{"200":{"description":"Current usage snapshot for the authenticated workspace. The response also includes the X-Request-Id, X-Usage-Cost, X-Credits-Used, and X-Credits-Remaining headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiUsageResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Read the current workspace usage snapshot","tags":["Usage"]}},"/v1/workspace/folders":{"get":{"description":"Returns the active workspace brandtracker folders so clients can resolve folderIds for workspace and brandtracker filters. Folder names are returned as metadata; prefer folderIds for exact filtering. Equivalent folder listing is also available at GET /v1/brandtrackers/folders.","operationId":"PublicApiWorkspaceController_getWorkspaceFolders","parameters":[],"responses":{"200":{"description":"Workspace brandtracker folders. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List workspace brandtracker folders","tags":["Workspace"]}},"/v1/workspace":{"get":{"description":"Returns the workspace bound to the provided public API key along with the effective authentication context.","operationId":"PublicApiWorkspaceController_getWorkspace","parameters":[],"responses":{"200":{"description":"Workspace snapshot for the authenticated public API credential. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiWorkspaceResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Inspect the authenticated workspace","tags":["Workspace"]}},"/v1/facets/categories":{"get":{"description":"Returns Google taxonomy category IDs currently available for public API category filters across shops, ads, emails, and advertisers.","operationId":"PublicApiFacetsController_getCategories","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring search over the facet label fields.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Category facet values with pagination and filter usage metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCategoryFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List public category facets","tags":["Facets"]}},"/v1/facets/shopify-apps":{"get":{"description":"Returns grouped Shopify app IDs currently available for public API Shopify app filters on shops and ads.","operationId":"PublicApiFacetsController_getShopifyApps","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring search over the facet label fields.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Shopify app facet values with pagination and filter usage metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiShopifyAppFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List public Shopify app facets","tags":["Facets"]}},"/v1/facets/technologies":{"get":{"description":"Returns supported technology slugs accepted by public API technology filters, enriched with metadata when available.","operationId":"PublicApiFacetsController_getTechnologies","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring search over the facet label fields.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Technology facet values with pagination and filter usage metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiTechnologyFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List public technology facets","tags":["Facets"]}},"/v1/facets/pixels":{"get":{"description":"Returns pixel technology UUIDs currently available for public API pixel filters on shops and ads.","operationId":"PublicApiFacetsController_getPixels","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring search over the facet label fields.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Pixel facet values with pagination and filter usage metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiPixelFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List public pixel facets","tags":["Facets"]}},"/v1/facets/themes":{"get":{"description":"Returns Shopify theme UUIDs currently available for public API theme filters on shops.","operationId":"PublicApiFacetsController_getThemes","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring search over the facet label fields.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Theme facet values with pagination and filter usage metadata. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiThemeFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List public Shopify theme facets","tags":["Facets"]}},"/v1/lookup":{"get":{"description":"Zero-credit lookup for brand names, shop domains, Facebook page ids, and Instagram handles. Exact matches are returned before fuzzy name matches.","operationId":"PublicApiLookupController_lookup","parameters":[{"name":"q","required":true,"in":"query","description":"Brand name, shop domain, Facebook page id, or Instagram handle.","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"type","required":false,"in":"query","description":"Limit lookup to one resource type, or search brandtrackers, advertisers, and shops with auto.","schema":{"type":"string","enum":["auto","brandtracker","advertiser","shop"],"default":"auto"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":10}}],"responses":{"200":{"description":"Lookup results linking known brandtracker, advertiser, and shop public identifiers. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiLookupResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Resolve a brand, advertiser, or shop","tags":["Discovery"]}},"/v1/lookup/facebook-shop":{"get":{"description":"Zero-credit resolver for deterministic Facebook page ↔ shop/site relationships. Provide exactly one Facebook page alias or one shop/site alias.","operationId":"PublicApiLookupController_resolveFacebookShop","parameters":[{"name":"facebook_id","required":false,"in":"query","description":"Facebook page id alias. Provide one Facebook page alias or one shop/site alias.","schema":{"type":"string","maxLength":128}},{"name":"facebookPageId","required":false,"in":"query","description":"Facebook page id alias. Provide one Facebook page alias or one shop/site alias.","schema":{"type":"string","maxLength":128}},{"name":"fb_page_id","required":false,"in":"query","description":"Facebook page id alias. Provide one Facebook page alias or one shop/site alias.","schema":{"type":"string","maxLength":128}},{"name":"shopId","required":false,"in":"query","description":"Shop/site id alias. Provide one shop/site alias or one Facebook page alias.","schema":{"type":"string","format":"uuid"}},{"name":"website_id","required":false,"in":"query","description":"Shop/site id alias. Provide one shop/site alias or one Facebook page alias.","schema":{"type":"string","format":"uuid"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"Ordered linked shops or Facebook pages, with a primary relationship convenience field. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Resolve Facebook page and shop relationships","tags":["Discovery"]}},"/v1/advertisers":{"get":{"description":"Returns the lightweight public advertisers collection. This endpoint stays intentionally simple and focuses on brand/domain search, pagination, ordering, and stable scalar filters. Use POST /v1/advertisers/query for the advanced discovery surface.","operationId":"PublicApiAdvertisersController_getAdvertisers","parameters":[{"name":"search","required":false,"in":"query","description":"Optional advertiser search keywords. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"searchType","required":false,"in":"query","description":"Simple search strategy for the advertisers collection. Use POST /v1/advertisers/query for advanced text resolution modes.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersListSearchType"}},{"name":"keywordMode","required":false,"in":"query","description":"How multiple search keywords should combine. Defaults to any.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersKeywordMode"}},{"name":"sortBy","required":false,"in":"query","description":"Primary sort key for advertiser discovery. Defaults to relevance.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersSortBy"}},{"name":"order","required":false,"in":"query","description":"Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersSortOrder"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","required":false,"in":"query","description":"Maximum number of advertisers to return. Defaults to 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"minFbPageCreationDate","required":false,"in":"query","description":"Inclusive lower bound for the Facebook page creation date filter.","schema":{"type":"string","format":"date"}},{"name":"maxFbPageCreationDate","required":false,"in":"query","description":"Inclusive upper bound for the Facebook page creation date filter.","schema":{"type":"string","format":"date"}},{"name":"minActiveAds","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxActiveAds","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"adsTimePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `current`, `last24h`, `last7d`, `last14d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersActiveAdsPeriod"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"minAdsLaunched","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxAdsLaunched","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"adsLaunchedPeriod","required":false,"in":"query","description":"Time window accepted by this request. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersAdsLaunchedPeriod"}},{"name":"minReach","required":false,"in":"query","description":"Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.","schema":{"type":"integer","minimum":0}},{"name":"maxReach","required":false,"in":"query","description":"Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.","schema":{"type":"integer","minimum":0}},{"name":"reachPeriod","required":false,"in":"query","description":"Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`, `total`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersReachPeriod"}},{"name":"pageType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `influencer`, `brand`.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertisersPageType"}}},{"name":"categoryIds","required":false,"in":"query","description":"Google category facet ids matched through linked websites' website_overview.google_categories. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"integer","minimum":1}}},{"name":"shopifyLinked","required":false,"in":"query","description":"Filter by indexed linked-site Shopify technology. `no` means no indexed Shopify technology is present for the advertiser.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersShopifyLinked"}},{"name":"gender","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `male`, `female`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertisersGender"}}],"responses":{"200":{"description":"Paginated advertisers response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdvertisersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List advertisers","tags":["Advertisers"]}},"/v1/advertisers/query":{"post":{"description":"Returns the advanced public advertisers query surface. This endpoint supports the current richer advertiser discovery filters through a structured public camelCase contract while keeping the response aligned with the standard public advertiser summary shape. categoryIds uses linked websites' google_categories; pageNiches remains an advanced legacy page-niche filter. Empty JSON bodies are valid and use defaults.","operationId":"PublicApiAdvertisersController_queryAdvertisers","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiAdvertisersRequestDto"},"examples":{"discovery":{"summary":"Find active brand advertisers with strong recent reach","value":{"search":["athleisure"],"searchType":"brand","sortBy":"reach","order":"desc","adsTimePeriod":"last7d","minActiveAds":10,"reachPeriod":"last14d","minReach":50000,"categoryIds":[254],"pageType":["brand"],"limit":20,"offset":0}},"emptyBodyDefaults":{"summary":"Empty object body is valid and uses default pagination/sort behavior","value":{}}}}}},"responses":{"200":{"description":"Paginated advertisers query response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdvertisersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query advertisers","tags":["Advertisers"]}},"/v1/advertisers/{advertiserId}/ads":{"get":{"description":"Returns a paginated list of ads for the requested page-centric advertiser. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.","operationId":"PublicApiAdvertisersController_getAdvertiserAds","parameters":[{"name":"advertiserId","required":true,"in":"path","description":"Public advertiser identifier. Current MVP uses the Facebook page id directly.","schema":{"example":"61554990830184","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"offset","required":false,"in":"query","schema":{"minimum":0,"default":0,"type":"integer"}},{"name":"status","required":false,"in":"query","description":"Filter ads by activity status. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertiserAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Filter ads by creative media type. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertiserAdsMediaType"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key for advertiser ads. `reach` uses the public reach/impressions metric; no `impressions` alias is accepted on this endpoint.","schema":{"$ref":"#/components/schemas/PublicApiAdvertiserAdsSortBy"}},{"name":"order","required":false,"in":"query","description":"Sort direction. Allowed values: `asc`, `desc`.","schema":{"$ref":"#/components/schemas/PublicApiAdvertiserAdsSortOrder"}},{"name":"cpm","required":false,"in":"query","schema":{"minimum":0,"default":9,"type":"integer"},"description":"Optional CPM override used to compute estimated spend in the ads response."}],"responses":{"200":{"description":"Paginated advertiser ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdvertiserAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Advertiser not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List ads for an advertiser","tags":["Advertisers"]}},"/v1/advertisers/{advertiserId}":{"get":{"description":"Returns the page-centric advertiser detail. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.","operationId":"PublicApiAdvertisersController_getAdvertiserDetail","parameters":[{"name":"advertiserId","required":true,"in":"path","description":"Public advertiser identifier. Current MVP uses the Facebook page id directly.","schema":{"example":"61554990830184","type":"string"}}],"responses":{"200":{"description":"Advertiser detail response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdvertiserDetailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Advertiser not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get advertiser detail","tags":["Advertisers"]}},"/v1/ads":{"get":{"description":"Returns the lightweight public ads collection. This endpoint stays intentionally small and focuses on text search, brand search, simple filters, sorting, and pagination. The search parameter is required; for advanced filtering without a required text search, use POST /v1/ads/query.","operationId":"PublicApiAdsController_getAds","parameters":[{"name":"search","required":true,"in":"query","description":"Canonical text query for the lightweight public ads listing.","schema":{"type":"string"}},{"name":"searchType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsListSearchType"},"description":"Search mode for this request. Allowed values: `adCopy`, `brand`."},{"name":"platform","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsPlatform"},"description":"Enum value accepted by this request. Allowed values: `facebook`, `all`. TikTok is not available in public v1."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsStatus"},"description":"Status filter for this request. Allowed values: `active`, `inactive`, `all`."},{"name":"mediaType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsMediaType"},"description":"Creative media type filter for this request. Allowed values: `image`, `video`, `carousel`. `carousel` maps to indexed carousel creatives and is not a DCO filter."},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsListSort"},"description":"Sort key for this request. Allowed values: `relevance`, `newest`, `longestRunning`, `reach`."},{"name":"query","required":false,"in":"query","deprecated":true,"schema":{"type":"string"},"description":"Deprecated alias for search. Use search instead."}],"responses":{"200":{"description":"Paginated ads response using the public ads contract. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiSearchAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List ads","tags":["Ads"]}},"/v1/ads/query":{"post":{"description":"Returns the advanced public ads query surface. This endpoint supports the full current ads filtering set through a public camelCase contract with structured JSON for advanced growth, country, market, and ranking filters while keeping the response aligned with the standard public ad summary shape. Search terms are optional in this route.","operationId":"PublicApiAdsController_queryAds","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiAdsRequestDto"},"examples":{"discoveryWithoutSearchTerm":{"summary":"Find active high-reach ads without a text search term","value":{"sortBy":"newest","order":"desc","status":"active","platforms":["facebook"],"minDaysRunning":7,"reachPeriod":"last7d","minReach":10000,"limit":25}},"topSevenDayScaling":{"summary":"Top ads scaling over the last 7 days","description":"Use 7-day reach delta sorting for natural-language prompts such as “top ads leggings femme sur les 7 derniers jours”. This does not add first-seen date filters unless createdAfter or adsTimePeriod is supplied.","value":{"search":["leggings femme"],"searchType":"adCopy","keywordMode":"all","sortBy":"reachDelta7d","order":"desc","reachPeriod":"last7d","minReach":1,"status":"active","platforms":["facebook"],"limit":20}}}}}},"responses":{"200":{"description":"Paginated advanced ads query response using the public ads contract. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiSearchAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query ads","tags":["Ads"]}},"/v1/ads/facets/landing-pages":{"get":{"description":"Aggregates distinct normalized landing-page URLs for Meta pages or one shop domain. Charges one credit per distinct URL returned and never returns ad rows.","operationId":"PublicApiAdsController_getLandingPages","parameters":[{"name":"scopeTrackedPages","required":false,"in":"query","description":"Repeated or comma-separated Meta/Facebook page identifiers. Mutually exclusive with scopeDomain.","schema":{"type":"array","items":{"type":"string","maxLength":128},"minItems":1,"maxItems":100}},{"name":"scopeDomain","required":false,"in":"query","description":"Shop URL or hostname. Mutually exclusive with scopeTrackedPages.","schema":{"type":"string","maxLength":253}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiAdsStatus"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Landing-page URL counts, active-ad counts, scope metadata, and truncation state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdLandingPagesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List landing pages","tags":["Ads"]}},"/v1/ads/{adId}/share":{"post":{"operationId":"PublicApiAdsController_createAdShare","parameters":[{"name":"adId","required":true,"in":"path","schema":{"example":"facebook_123456789","type":"string"},"description":"Trendtrack ad identifier returned as `adId` by the Public API."}],"responses":{"200":{"description":"Public ad share URL response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateAdShareResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No ad matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create or return an ad share URL","tags":["Ads"],"description":"Creates or returns the existing Trendtrack public webapp share URL for an ad. This is classified as a workspace-scoped write because it creates share state server-side when needed; delegated OAuth/API-key callers must be workspace writers."},"delete":{"operationId":"PublicApiAdsController_deleteAdShare","parameters":[{"name":"adId","required":true,"in":"path","schema":{"example":"facebook_123456789","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteAdShareResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete an ad share URL","tags":["Ads"]}},"/v1/ads/{adId}/media-url":{"get":{"operationId":"PublicApiAdsController_getAdMediaUrl","parameters":[{"name":"adId","required":true,"in":"path","schema":{"example":"facebook_123456789","type":"string"},"description":"Trendtrack ad identifier returned as `adId` by the Public API."}],"responses":{"200":{"description":"Public ad media URL response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdMediaUrlResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No ad matches the requested id, or no media URL is available for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get an ad media URL","tags":["Ads"],"description":"Returns URL metadata for the best available media asset for an ad. This endpoint does not proxy or download the binary media."}},"/v1/ads/{adId}":{"get":{"operationId":"PublicApiAdsController_getAdDetail","parameters":[{"name":"adId","required":true,"in":"path","schema":{"example":"facebook_123456789","type":"string"},"description":"Trendtrack ad identifier returned as `adId` by the Public API."}],"responses":{"200":{"description":"Public ad detail response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdDetailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No ad matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get an ad by id","tags":["Ads"],"description":"Returns a single public ad detail object by ad id. The current backing identifier is the internal composite ad id, but the public contract exposes it as id."}},"/v1/ads/{adId}/reach-history":{"get":{"operationId":"PublicApiAdsController_getAdReachHistory","parameters":[{"name":"adId","required":true,"in":"path","schema":{"example":"facebook_123456789","type":"string"},"description":"Trendtrack ad identifier returned as `adId` by the Public API."},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":365}}],"responses":{"200":{"description":"Public ad reach history response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetAdReachHistoryResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No ad matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get ad reach history","tags":["Ads"],"description":"Returns the public daily reach history for one ad. The series is intentionally lightweight and keeps reach as the canonical metric term."}},"/v1/google-ads/query":{"post":{"description":"Queries the dedicated Google Ads library. Networks, audience countries, and Google category ids map to verified google-ads-search fields.","operationId":"PublicApiGoogleAdsController_queryAds","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiGoogleAdsRequestDto"},"examples":{"shoppingByCategoryAndCountry":{"summary":"US Shopping ads in Women’s Clothing","value":{"status":"active","networks":["shopping"],"categoryIds":[24],"audienceCountries":{"include":["US"]},"sortBy":"newest","order":"desc","page":1,"limit":25}}}}}},"responses":{"200":{"description":"Paginated Google Ads response. One returned ad is one billable ads credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGoogleAdsQueryResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query Google Ads","tags":["Google Ads"]}},"/v1/google-ads/facets/networks":{"get":{"description":"Returns the normalized Google delivery networks accepted by POST /v1/google-ads/query.","operationId":"PublicApiGoogleAdsController_listNetworks","parameters":[],"responses":{"200":{"description":"Google delivery networks with live ad counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGoogleAdsFacetResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List Google Ads network facets","tags":["Google Ads"]}},"/v1/google-ads/facets/countries":{"get":{"description":"Returns audience country codes observed in the Google Ads search index.","operationId":"PublicApiGoogleAdsController_listCountries","parameters":[{"name":"search","required":false,"in":"query","schema":{"maxLength":200,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":500,"default":100,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"offset","required":false,"in":"query","schema":{"minimum":0,"default":0,"allOf":[{"$ref":"#/components/schemas/Object"}]}}],"responses":{"200":{"description":"Google audience countries with live ad counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGoogleAdsFacetResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List Google Ads audience-country facets","tags":["Google Ads"]}},"/v1/google-ads/facets/categories":{"get":{"description":"Returns the Google category ids accepted by categoryIds on POST /v1/google-ads/query.","operationId":"PublicApiGoogleAdsController_listCategories","parameters":[{"name":"search","required":false,"in":"query","schema":{"maxLength":200,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":500,"default":100,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"offset","required":false,"in":"query","schema":{"minimum":0,"default":0,"allOf":[{"$ref":"#/components/schemas/Object"}]}}],"responses":{"200":{"description":"Paginated Google categories with advertiser usage counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGoogleAdsCategoryFacetsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List Google Ads category facets","tags":["Google Ads"]}},"/v1/shops":{"get":{"operationId":"PublicApiShopsController_getShops","parameters":[{"name":"search","required":false,"in":"query","description":"Optional broad shop identity search term matched against domain, related domains, and shop name. This GET browse search remains broad; use POST /v1/shops/query with searchType=\"domain\" for exact domain matching.","schema":{"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional sort key for the shops list. Defaults to monthlyVisits.","schema":{"$ref":"#/components/schemas/PublicApiShopsSortBy"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiSortOrder"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","required":false,"in":"query","description":"Maximum number of shops to return. Defaults to 32.","schema":{"type":"integer","minimum":1,"maximum":100,"default":32}},{"name":"minMonthlyVisits","required":false,"in":"query","description":"Optional minimum monthly visits filter.","schema":{"type":"integer","minimum":0}},{"name":"maxMonthlyVisits","required":false,"in":"query","description":"Optional maximum monthly visits filter.","schema":{"type":"integer","minimum":0}},{"name":"minActiveAds","required":false,"in":"query","description":"Optional minimum active ads filter. The metric follows adsTimePeriod.","schema":{"minimum":0,"type":"number"}},{"name":"maxActiveAds","required":false,"in":"query","description":"Optional maximum active ads filter. The metric follows adsTimePeriod.","schema":{"minimum":0,"type":"number"}},{"name":"adsTimePeriod","required":false,"in":"query","description":"Optional time period used by active ads filters and sorting. Defaults to last24h.","schema":{"$ref":"#/components/schemas/PublicApiAdsTimePeriod"}},{"name":"hasTikTok","required":false,"in":"query","description":"Optional TikTok presence filter backed by the legacy flat shop index. true requires an indexed TikTok page or handle; false excludes shops with one.","schema":{"example":true,"type":"boolean"}},{"name":"minTikTokFollowers","required":false,"in":"query","schema":{"minimum":0,"example":10000,"type":"number"}},{"name":"maxTikTokFollowers","required":false,"in":"query","schema":{"minimum":0,"example":500000,"type":"number"}},{"name":"minTikTokActiveAds","required":false,"in":"query","schema":{"minimum":0,"example":5,"type":"number"}},{"name":"maxTikTokActiveAds","required":false,"in":"query","schema":{"minimum":0,"example":50,"type":"number"}},{"name":"minTikTokTotalPosts","required":false,"in":"query","schema":{"minimum":0,"example":20,"type":"number"}},{"name":"maxTikTokTotalPosts","required":false,"in":"query","schema":{"minimum":0,"example":1000,"type":"number"}},{"name":"minProductsCount","required":false,"in":"query","description":"Optional minimum products count filter.","schema":{"type":"integer","minimum":0}},{"name":"maxProductsCount","required":false,"in":"query","description":"Optional maximum products count filter.","schema":{"type":"integer","minimum":0}},{"name":"createdAfter","required":false,"in":"query","description":"Optional inclusive lower bound for shop creation date.","schema":{"format":"date","type":"string"}},{"name":"createdBefore","required":false,"in":"query","description":"Optional inclusive upper bound for shop creation date.","schema":{"format":"date","type":"string"}},{"name":"isShopifyPlus","required":false,"in":"query","description":"Optional Shopify Plus filter.","schema":{"type":"boolean"}},{"name":"categoryIds","required":false,"in":"query","description":"Optional category ids. Uses the same index field as POST /v1/shops/query categoryIds.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"integer"}}},{"name":"pixelIds","required":false,"in":"query","description":"Optional canonical pixel UUIDs. Uses the same index fields as POST /v1/shops/query pixelIds. Resolve display names through /v1/facets/pixels.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"excludePixelIds","required":false,"in":"query","description":"Optional canonical pixel UUIDs to exclude. Uses the same index fields as POST /v1/shops/query excludePixelIds.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"shopifyAppIds","required":false,"in":"query","description":"Optional canonical Shopify app UUIDs. Uses the same index field as POST /v1/shops/query shopifyAppIds.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"excludeShopifyAppIds","required":false,"in":"query","description":"Optional canonical Shopify app UUIDs to exclude. Uses the same index field as POST /v1/shops/query excludeShopifyAppIds.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"languages","required":false,"in":"query","description":"Optional default language filters. Accepts repeated query params or a comma-separated list.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"currencies","required":false,"in":"query","description":"Optional default currency filters. Accepts repeated query params or a comma-separated list.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"minTrustpilotRating","required":false,"in":"query","description":"Optional minimum Trustpilot rating filter.","schema":{"minimum":0,"type":"number"}},{"name":"maxTrustpilotRating","required":false,"in":"query","description":"Optional maximum Trustpilot rating filter.","schema":{"minimum":0,"type":"number"}},{"name":"minTrustpilotReviewCount","required":false,"in":"query","description":"Optional minimum Trustpilot reviews filter.","schema":{"type":"integer","minimum":0}},{"name":"maxTrustpilotReviewCount","required":false,"in":"query","description":"Optional maximum Trustpilot reviews filter.","schema":{"type":"integer","minimum":0}},{"name":"minMonthlySales","required":false,"in":"query","description":"Minimum estimated revenue over the last 30 days, in USD (sales tracker). Shops the tracker does not follow are excluded.","schema":{"type":"integer","minimum":0}},{"name":"maxMonthlySales","required":false,"in":"query","description":"Maximum estimated revenue over the last 30 days, in USD (sales tracker).","schema":{"type":"integer","minimum":0}},{"name":"minUnitsSold","required":false,"in":"query","description":"Minimum units sold over the last 30 days (sales tracker). Shops the tracker does not follow are excluded.","schema":{"type":"integer","minimum":0}},{"name":"maxUnitsSold","required":false,"in":"query","description":"Maximum units sold over the last 30 days (sales tracker).","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Paginated shops response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List shops","tags":["Shops"],"description":"Returns the lightweight public shops browse surface. This endpoint stays intentionally simple and covers the default discovery path through search, pagination, sorting, and a small stable subset of filters. For the full advanced filtering contract, use POST /v1/shops/query."}},"/v1/shops/query":{"post":{"operationId":"PublicApiShopsController_queryShops","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiShopsRequestDto"},"examples":{"exactDomain":{"summary":"Find one shop by exact domain or URL (domain/related-domain exact matching)","value":{"search":"https://www.allbirds.com/products","searchType":"domain","limit":10,"offset":0}},"discovery":{"summary":"Find growing shops by product text in the US market","value":{"search":"pet products","searchType":"productName","sortBy":"monthlyVisits","order":"desc","adsTimePeriod":"last7d","minActiveAds":10,"minMonthlyVisits":5000,"mainMarketCountries":["US"],"limit":25,"offset":0}},"shopContains":{"summary":"Find shops with broad website text search","value":{"search":"organic cotton","searchType":"shopContains","limit":25,"offset":0}}}}}},"responses":{"200":{"description":"Paginated advanced shops query response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query shops","tags":["Shops"],"description":"Returns the advanced public shops discovery surface. This endpoint is the canonical public route for complex filtering and sorting, while keeping the response aligned with the standard public ShopSummary contract. searchType=domain performs exact domain/related-domain matching from a domain or URL and does not fall back to broad wildcard/text matching."}},"/v1/shops/{identifier}/similar":{"get":{"description":"Returns a paginated list of similar shops using the public hybrid shops contract. The identifier can be a canonical domain or a public shop id / website UUID. When the resolved shop is not present in the similar shops engine, the endpoint still returns 200 with an empty data array and meta.shopExists=false.","operationId":"PublicApiShopsController_getSimilarShops","parameters":[{"name":"identifier","required":true,"in":"path","description":"Canonical shop domain or stable public shop id / website UUID used to resolve similar shops.","schema":{"example":"example.com","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key for similar shops. createdAt uses request-time normalization while the backing creation_date field remains keyword-mapped; native date sorting requires an Elasticsearch mapping/reindex update.","schema":{"$ref":"#/components/schemas/PublicApiSimilarShopsSortBy"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiSortOrder"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","required":false,"in":"query","description":"Maximum number of similar shops to return. Defaults to 32.","schema":{"type":"integer","minimum":1,"maximum":100,"default":32}}],"responses":{"200":{"description":"Paginated similar shops response for the requested identifier. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetSimilarShopsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"A UUID-shaped shop identifier was provided but no matching shop was found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List shops similar to a domain or shop id","tags":["Shops"]}},"/v1/products/image-search":{"post":{"description":"Finds the store products that look like an image, most similar first, one per shop by default (maxPerShop) and with the storefronts of one brand counted as one shop (groupBrands). Send the image as a multipart file or as a public URL; read the next pages with the returned searchId. Costs 4 credits per product returned.","operationId":"PublicApiProductsController_searchByImage","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicApiProductImageSearchRequestDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiProductImageSearchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiProductImageSearchResponseDto"}}}},"400":{"description":"No image, more than one image, an unsupported file type, or an image that cannot be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The searchId is unknown to this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"413":{"description":"The image file is larger than 10 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Search products by image","tags":["Shops"]}},"/v1/shops/image-search":{"post":{"description":"Finds the shops selling products that look like an image, the most active advertisers (Meta active ads) first, each with its most similar products. The storefronts of one brand come back as one row with otherStorefronts, billed once (groupBrands). Send the image as a multipart file or as a public URL; read the next pages with the returned searchId. Costs 4 credits per shop returned.","operationId":"PublicApiShopsController_searchByImage","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicApiShopImageSearchRequestDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiShopImageSearchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiShopImageSearchResponseDto"}}}},"400":{"description":"No image, more than one image, an unsupported file type, or an image that cannot be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The searchId is unknown to this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"413":{"description":"The image file is larger than 10 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Search shops by image","tags":["Shops"]}},"/v1/shops/{shopId}/advertisers":{"get":{"description":"Returns the linked advertiser summaries for a single shop identifier.","operationId":"PublicApiShopsController_getShopAdvertisers","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":100,"type":"integer"}}],"responses":{"200":{"description":"Linked advertisers response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopAdvertisersResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List advertisers linked to a shop","tags":["Shops"]}},"/v1/shops/{shopId}/socials/history":{"get":{"description":"Returns follower time-series for Facebook and Instagram for the linked advertiser page of the shop. Other networks are handle-only today and not exposed here.","operationId":"PublicApiShopsController_getShopSocialsHistory","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}},{"name":"period","required":false,"in":"query","description":"Aggregation bucket for the follower time series. Week and month pick the last raw snapshot of each bucket.","schema":{"$ref":"#/components/schemas/PublicApiShopSocialsHistoryPeriod"}},{"name":"days","required":false,"in":"query","description":"Rolling lookback window, in days, ending at the latest snapshot.","schema":{"minimum":7,"maximum":365,"default":90,"type":"integer"}}],"responses":{"200":{"description":"Follower time-series response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopSocialsHistoryResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get shop social follower history","tags":["Shops"]}},"/v1/shops/{shopId}/sales/history":{"get":{"description":"Returns the daily readings of the sales tracker for a shop: estimated revenue and units sold, each over the 30 days before the reading. Estimates, in USD. Costs 4 credits per call.","operationId":"PublicApiShopsController_getShopSalesHistory","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}},{"name":"period","required":false,"in":"query","description":"One reading per day, week or month. Week and month keep the last daily reading of each bucket; readings are never summed, since each one already covers the 30 days before it.","schema":{"$ref":"#/components/schemas/PublicApiShopSalesHistoryPeriod"}},{"name":"days","required":false,"in":"query","description":"Rolling lookback window, in days, ending at the latest reading.","schema":{"minimum":7,"maximum":365,"default":90,"type":"integer"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopSalesHistoryResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get shop sales history","tags":["Shops"]}},"/v1/shops/{shopId}/products":{"get":{"description":"Returns the paginated list of Shopify best-selling products for a single shop. Products come from the shop’s Shopify best-seller feed and can be sorted by rank, price, or creation date.","operationId":"PublicApiShopsController_getShopProducts","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of products to return per page.","schema":{"minimum":1,"maximum":100,"default":32,"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"Offset into the products list.","schema":{"minimum":0,"maximum":10000,"default":0,"type":"integer"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key. `popularity` orders by Shopify best-seller rank; `price` by product price; `createdAt` by Shopify product creation date.","schema":{"$ref":"#/components/schemas/PublicApiShopProductsSortBy"}},{"name":"order","required":false,"in":"query","description":"Sort direction. Defaults to `asc` for `popularity` and `desc` otherwise.","schema":{"$ref":"#/components/schemas/PublicApiSortOrder"}}],"responses":{"200":{"description":"Paginated shop products response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopProductsResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List shop products","tags":["Shops"]}},"/v1/shops/{shopId}":{"get":{"description":"Returns the public hybrid shop detail read model for a single shop identifier.","operationId":"PublicApiShopsController_getShop","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}}],"responses":{"200":{"description":"Detailed public shop response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get a shop by id","tags":["Shops"]}},"/v1/tiktok/library":{"get":{"description":"Returns TikTok ads and organic videos from the Public API TikTok library. This namespace is separate from the Meta-only /v1/ads endpoints and is backed by the tiktoks-search Elasticsearch alias.","operationId":"PublicApiTikTokController_listLibrary","parameters":[{"name":"search","required":false,"in":"query","schema":{"type":"string","maxLength":500}},{"name":"searchArea","required":false,"in":"query","schema":{"type":"string","enum":["all","caption","profile","hashtag","music"],"default":"all"}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["all","ad","organic"],"default":"all"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["all","active","inactive"],"default":"all"}},{"name":"mediaTypes","required":false,"in":"query","schema":{"type":"array","maxItems":20,"items":{"type":"string","enum":["image","video","carousel"]}}},{"name":"languages","required":false,"in":"query","description":"ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.","schema":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":500}}},{"name":"countries","required":false,"in":"query","schema":{"type":"array","maxItems":20,"items":{"type":"string","pattern":"^[A-Z]{2}$"}}},{"name":"hashtags","required":false,"in":"query","description":"Hashtags with or without #, case-insensitive.","schema":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":500}}},{"name":"tiktokPageId","required":false,"in":"query","schema":{"type":"string","maxLength":255}},{"name":"domain","required":false,"in":"query","schema":{"type":"string","maxLength":253}},{"name":"handle","required":false,"in":"query","schema":{"type":"string","maxLength":64}},{"name":"publishedAfter","required":false,"in":"query","schema":{"type":"string","format":"date-time"}},{"name":"publishedBefore","required":false,"in":"query","schema":{"type":"string","format":"date-time"}},{"name":"minViews","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxViews","required":false,"in":"query","schema":{"type":"integer","minimum":0}},{"name":"minEngagementRate","required":false,"in":"query","schema":{"type":"number","minimum":0}},{"name":"maxEngagementRate","required":false,"in":"query","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"sortBy","required":false,"in":"query","schema":{"type":"string","enum":["relevance","newest","updatedAt","views","likes","comments","shares","saves","engagementRate","daysRunning","followers"],"default":"newest"}},{"name":"order","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1,"$ref":"#/components/schemas/Object"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25,"$ref":"#/components/schemas/Object"}}],"responses":{"200":{"description":"Paginated TikTok library response. One returned TikTok item is one billable ads credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiTikTokLibraryResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List TikTok library items","tags":["TikTok"]}},"/v1/tiktok/library/query":{"post":{"description":"Advanced TikTok library query over ES-backed fields only. It intentionally does not use the internal Next /api/tiktok-ads route or per-request Postgres hydration.","operationId":"PublicApiTikTokController_queryLibrary","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiTikTokLibraryRequestDto"},"examples":{"activeAdsByCaption":{"summary":"Find active TikTok ads by caption text","value":{"search":["protein gummies"],"searchArea":"caption","type":"ad","status":"active","minViews":10000,"sortBy":"views","order":"desc","limit":10}}}}}},"responses":{"200":{"description":"Paginated TikTok library query response. One returned TikTok item is one billable ads credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiTikTokLibraryResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query TikTok library items","tags":["TikTok"]}},"/v1/tiktok/library/{itemId}":{"get":{"description":"Returns one TikTok library item detail by composite_ad_id, with tiktok_id fallback because tiktok_id is part of the tiktoks-search public ES contract.","operationId":"PublicApiTikTokController_getLibraryItem","parameters":[{"name":"itemId","required":true,"in":"path","schema":{"example":"tiktok_7078586231734521093","type":"string"}}],"responses":{"200":{"description":"TikTok library detail response. One found TikTok item is one billable ads credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiTikTokLibraryDetailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No TikTok library item matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get a TikTok library item","tags":["TikTok"]}},"/v1/shops/{shopId}/tiktok/library":{"get":{"description":"Returns TikTok library items linked to one public shop id using exact ES shop identifiers. This route has a TikTok endpoint key and ads entitlement even though it is nested under /v1/shops.","operationId":"PublicApiTikTokController_listShopLibrary","parameters":[{"name":"shopId","required":true,"in":"path","description":"Stable public shop identifier.","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string","example":"protein gummies"}},{"name":"searchArea","required":false,"in":"query","schema":{"type":"string","enum":["all","caption","profile","hashtag","music"],"default":"all"}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["all","ad","organic"],"default":"all"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["all","active","inactive"],"default":"all"}},{"name":"mediaTypes","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["image","video","carousel"]}}},{"name":"languages","required":false,"in":"query","description":"ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.","schema":{"type":"array","example":["en","fr"],"items":{"type":"string"}}},{"name":"countries","required":false,"in":"query","schema":{"type":"array","example":["US","FR"],"items":{"type":"string"}}},{"name":"hashtags","required":false,"in":"query","description":"Hashtags with or without #, case-insensitive.","schema":{"type":"array","example":["beauty","makeup"],"items":{"type":"string"}}},{"name":"tiktokPageId","required":false,"in":"query","schema":{"type":"string","example":"1234567890123456789"}},{"name":"domain","required":false,"in":"query","schema":{"type":"string","example":"example.com"}},{"name":"handle","required":false,"in":"query","schema":{"type":"string","example":"examplebrand"}},{"name":"publishedAfter","required":false,"in":"query","schema":{"type":"string","example":"2026-01-01"}},{"name":"publishedBefore","required":false,"in":"query","schema":{"type":"string","example":"2026-06-05"}},{"name":"minViews","required":false,"in":"query","schema":{"type":"number","example":10000}},{"name":"maxViews","required":false,"in":"query","schema":{"type":"number","example":1000000}},{"name":"minEngagementRate","required":false,"in":"query","schema":{"type":"number","example":5}},{"name":"maxEngagementRate","required":false,"in":"query","schema":{"type":"number","example":100}},{"name":"sortBy","required":false,"in":"query","schema":{"type":"string","enum":["relevance","newest","updatedAt","views","likes","comments","shares","saves","engagementRate","daysRunning","followers"],"default":"newest"}},{"name":"order","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":25,"allOf":[{"$ref":"#/components/schemas/Object"}]}}],"responses":{"200":{"description":"Paginated shop-scoped TikTok library response. One returned TikTok item is one billable ads credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiTikTokLibraryResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List TikTok library items for a shop","tags":["TikTok"]}},"/v1/emails/query":{"post":{"description":"Returns the advanced public emails discovery surface. This endpoint is the canonical public route for richer email filters while keeping the response aligned with the stable public EmailSummary contract. The API does not expose opens, clicks, conversions, or revenue metrics; sorting is discovery-oriented metadata ordering, not best-performance scoring.","operationId":"PublicApiEmailsController_queryEmails","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPublicApiEmailsRequestDto"},"examples":{"discovery":{"summary":"Find recent promotional emails from high-traffic shops","value":{"search":["welcome","discount"],"searchType":"email","keywordMode":"any","sortBy":"newest","order":"desc","minMonthlyVisits":20000,"promotionTypes":["Discount"],"shopifyPlan":"plus","page":1,"limit":25}}}}}},"responses":{"200":{"description":"Paginated advanced emails query response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetEmailsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Query emails","tags":["Emails"]}},"/v1/emails/{emailId}/html":{"get":{"description":"Returns the raw captured HTML for one public email identifier. Existing emails may have html=null when raw HTML is unavailable.","operationId":"PublicApiEmailsController_getEmailHtml","parameters":[{"name":"emailId","required":true,"in":"path","schema":{"example":123456,"type":"string"},"description":"Stable public email identifier."}],"responses":{"200":{"description":"Raw email HTML response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetEmailHtmlResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No email matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get raw email HTML by id","tags":["Emails"]}},"/v1/emails/{emailId}":{"get":{"operationId":"PublicApiEmailsController_getEmail","parameters":[{"name":"emailId","required":true,"in":"path","schema":{"example":123456,"type":"string"},"description":"Stable public email identifier."}],"responses":{"200":{"description":"Public email detail response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetEmailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No email matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get an email by id","tags":["Emails"],"description":"Returns one public email detail object by stable email identifier, including the clean public shop context nested under the email."}},"/v1/shops/{shopId}/emails":{"get":{"operationId":"PublicApiShopEmailsController_getShopEmails","parameters":[{"name":"shopId","required":true,"in":"path","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"},"description":"Stable public shop identifier."},{"name":"search","required":false,"in":"query","description":"Optional email search keywords. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"sortBy","required":false,"in":"query","description":"Sort key for this request. Allowed values: `newest`, `oldest`, `relevance`, `event`, `promotionType`. These are discovery/indexing sorts, not opens/clicks/conversions performance rankings.","schema":{"$ref":"#/components/schemas/PublicApiShopEmailsSortBy"}},{"name":"sentAfter","required":false,"in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sentBefore","required":false,"in":"query","schema":{"type":"string","format":"date-time"}},{"name":"campaignTypes","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"languages","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated shop emails response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetEmailsResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List emails for a shop","tags":["Emails"],"description":"Returns the paginated public emails linked to one shop identifier, with stable recency-oriented filters and the same public EmailSummary response contract as the global emails surface."}},"/v1/shops/{shopId}/emails/stats":{"get":{"description":"Returns shop-scoped 90-day email frequency stats and sparse UTC calendar counts for one requested month.","operationId":"PublicApiShopEmailsController_getShopEmailStats","parameters":[{"name":"shopId","required":true,"in":"path","schema":{"example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","type":"string"},"description":"Stable public shop identifier."},{"name":"month","required":true,"in":"query","description":"Calendar month to aggregate, formatted as YYYY-MM.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","example":"2026-04"}}],"responses":{"200":{"description":"Shop email stats response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetShopEmailStatsResponseDto"}}}},"400":{"description":"The shopId path parameter is not a canonical UUID. Possible error code: bad_request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The requested shop was not found. Possible error code: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get shop email stats","tags":["Emails"]}},"/v1/brandtrackers":{"post":{"operationId":"PublicApiBrandtrackersController_createBrandtracker","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiBrandtrackerBodyDto"}}}},"responses":{"200":{"description":"Brandtracker creation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateBrandtrackerResponseDto"}}}},"201":{"description":"Brandtracker created or reactivated. Already-active idempotent calls return 200 with created=false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateBrandtrackerResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"402":{"description":"`quota_exhausted`: every tracked-brand slot of the plan is taken. A removed brand keeps its slot for 24h, so `details.reservedByCooldown` slots may be held by recent removals; `details.nextSlotAvailableAt` says when one frees.","headers":{"Retry-After":{"description":"Seconds until a cooldown ends and frees a slot. Absent when no cooldown can free one.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerQuotaExhaustedResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"Create target could not be resolved uniquely. Possible error code: ambiguous_target for domain aliases that match multiple websites.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"429":{"description":"The Pro plan persistent brandtracker create/delete mutation quota is exhausted. Business and Agency plans have no create/delete mutation quota. Response includes Retry-After, RateLimit-Limit, RateLimit-Remaining: 0, and X-RateLimit-Window: utc_day. Active brandtracker allowance exhaustion is returned before any state change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a brandtracker","tags":["Brandtrackers"],"description":"Creates or reactivates a workspace brandtracker by exactly one target identifier: facebookPageId, websiteId, shopId (alias of websiteId), or domain. Domains are normalized and must resolve to exactly one known website. State-changing create/reactivate requests consume one brandtracker create/delete quota unit and one active brandtracker slot; already-active no-ops return 200 and cost 0 units."},"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackers","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"}},{"name":"hasNewAdsSince","required":false,"in":"query","description":"ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.","schema":{"format":"date-time","type":"string"}},{"name":"name","required":false,"in":"query","description":"Case-insensitive contains match against brandtracker name.","schema":{"maxLength":200,"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackersSortBy"}},{"name":"folderIds","required":false,"in":"query","description":"Folder ids. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"integer","minimum":1}}},{"name":"folderNames","required":false,"in":"query","description":"Folder name search terms. Matches are case-insensitive contains checks. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Paginated brandtrackers response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtrackers","tags":["Brandtrackers"],"description":"Returns the workspace-scoped active brandtrackers attached to the authenticated public API workspace. The public identifier is brandtracker.id; legacy spyders.uuid values are accepted when migration metadata exists."}},"/v1/brandtrackers/folders":{"post":{"operationId":"PublicApiBrandtrackersController_createBrandtrackerFolder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiBrandtrackerFolderBodyDto"}}}},"responses":{"200":{"description":"Brandtracker folder creation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerFolderMutationResponseDto"}}}},"201":{"description":"Brandtracker folder created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerFolderMutationResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a brandtracker folder","tags":["Brandtrackers"],"description":"Creates a workspace brandtracker folder and assigns the next rank atomically. Folder mutations are workspace-scoped, metered, and audited."},"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerFolders","parameters":[],"responses":{"200":{"description":"Brandtracker folders. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker folders","tags":["Brandtrackers"],"description":"Returns the active workspace brandtracker folders so clients can resolve folder ids for brandtracker filters. Equivalent folder listing is also available at GET /v1/workspace/folders."}},"/v1/brandtrackers/folders/{folderId}":{"patch":{"operationId":"PublicApiBrandtrackersController_renameBrandtrackerFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenamePublicApiBrandtrackerFolderBodyDto"}}}},"responses":{"200":{"description":"Brandtracker folder rename response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerFolderMutationResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Rename a brandtracker folder","tags":["Brandtrackers"],"description":"Renames a workspace brandtracker folder. The folder id must belong to the authenticated workspace; cross-workspace ids are returned as not found before any state change."},"delete":{"operationId":"PublicApiBrandtrackersController_deleteBrandtrackerFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePublicApiBrandtrackerFolderBodyDto"}}}},"responses":{"200":{"description":"Brandtracker folder delete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteBrandtrackerFolderResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"429":{"description":"The Pro plan persistent brandtracker create/delete mutation quota is exhausted. Business and Agency plans have no create/delete mutation quota. Response includes Retry-After, RateLimit-Limit, RateLimit-Remaining: 0, and X-RateLimit-Window: utc_day. Active brandtracker allowance exhaustion is returned before any state change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a brandtracker folder","tags":["Brandtrackers"],"description":"Deletes a workspace folder. move-to-default moves active brandtrackers to root; delete-brandtrackers deactivates affected workspace links. confirm must be true. The delete-brandtrackers action consumes one persistent brandtracker create/delete quota operation for the whole folder and decrements active brandtracker usage by the affected active-link count; no partial mutation is committed when quota is exhausted."}},"/v1/brandtrackers/workspace-links":{"patch":{"description":"Moves active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. The destination folder id must belong to the authenticated workspace; null moves links to root. Move operations are metered and audited but do not consume persistent create/delete quota or change active brandtracker usage.","operationId":"PublicApiBrandtrackersController_moveBrandtrackerWorkspaceLinks","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovePublicApiBrandtrackerWorkspaceLinksBodyDto"}}}},"responses":{"200":{"description":"Brandtracker workspace-link move response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerWorkspaceLinksMutationResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Replace brandtracker folder memberships","tags":["Brandtrackers"]},"delete":{"operationId":"PublicApiBrandtrackersController_deleteBrandtrackerWorkspaceLinks","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePublicApiBrandtrackerWorkspaceLinksBodyDto"}}}},"responses":{"200":{"description":"Brandtracker workspace-link delete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerWorkspaceLinksMutationResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"429":{"description":"The Pro plan persistent brandtracker create/delete mutation quota is exhausted. Business and Agency plans have no create/delete mutation quota. Response includes Retry-After, RateLimit-Limit, RateLimit-Remaining: 0, and X-RateLimit-Window: utc_day. Active brandtracker allowance exhaustion is returned before any state change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Bulk delete brandtracker workspace links","tags":["Brandtrackers"],"description":"Deactivates active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. confirm must be true. Bulk delete consumes one persistent brandtracker create/delete quota operation for the request, reports requested/affected/not-found ids, and decrements active brandtracker usage by the affected active-link count."}},"/v1/brandtrackers/{brandtrackerId}":{"delete":{"operationId":"PublicApiBrandtrackersController_deleteBrandtracker","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."}],"responses":{"200":{"description":"Brandtracker delete response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteBrandtrackerResponseDto"}}}},"400":{"description":"Invalid mutation request. Possible error codes: validation_failed, bad_request. Create accepts exactly one of facebookPageId, websiteId, shopId, or domain; destructive folder/workspace-link deletes require confirm: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"Workspace-owned folder, brandtracker, workspace link, page, or domain target was not found. Cross-workspace ids are reported safely as not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"429":{"description":"The Pro plan persistent brandtracker create/delete mutation quota is exhausted. Business and Agency plans have no create/delete mutation quota. Response includes Retry-After, RateLimit-Limit, RateLimit-Remaining: 0, and X-RateLimit-Window: utc_day. Active brandtracker allowance exhaustion is returned before any state change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a brandtracker","tags":["Brandtrackers"],"description":"Marks the workspace brandtracker inactive while preserving the workspace link and workspace-scoped metadata for reconstructability/reactivation. The shared global brandtracker row is preserved."},"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerDetail","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."}],"responses":{"200":{"description":"Brandtracker detail response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerDetailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No active workspace brandtracker matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get a brandtracker","tags":["Brandtrackers"],"description":"Returns the detail payload for one active workspace brandtracker resolved from brandtracker.id."}},"/v1/brandtrackers/folders/{folderId}/brandtrackers":{"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackersInFolder","parameters":[{"name":"folderId","required":true,"in":"path","description":"Workspace brandtracker folder id.","schema":{"type":"integer","minimum":1}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"}},{"name":"hasNewAdsSince","required":false,"in":"query","description":"ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.","schema":{"format":"date-time","type":"string"}},{"name":"name","required":false,"in":"query","description":"Case-insensitive contains match against brandtracker name.","schema":{"maxLength":200,"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackersSortBy"}}],"responses":{"200":{"description":"Paginated folder brandtrackers response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtrackers in a folder","tags":["Brandtrackers"],"description":"Returns the workspace-scoped active brandtrackers assigned to the requested folder. This is equivalent to /v1/brandtrackers?folderIds=:folderId."}},"/v1/brandtrackers/{brandtrackerId}/snapshots":{"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerSnapshots","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of snapshot dates to return. Defaults to 100.","schema":{"minimum":1,"maximum":365,"default":100,"type":"integer"}}],"responses":{"200":{"description":"Paginated brandtracker snapshot dates response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerSnapshotsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No active workspace brandtracker matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker snapshot dates","tags":["Brandtrackers"],"description":"Returns available ad reach snapshot dates and readiness status for one active workspace brandtracker. latestDate is preserved as a compatibility alias of latestReadyDate; snapshotDate=latest resolves to the latest ready date."}},"/v1/brandtrackers/{brandtrackerId}/ads":{"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerAds","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key. The adOrder value also accepts ad_order and ad-order aliases.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSort"}},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes for ad copy descriptions.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Comma-separated country include/exclude filters.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partners","required":false,"in":"query","description":"When true, keep only partnership ads. When false, keep only non-partnership ads.","schema":{"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"Paginated brandtracker ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No active workspace brandtracker matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker ads","tags":["Brandtrackers"],"description":"Returns the Meta ads for one active workspace brandtracker resolved from brandtracker.id to fb_page_id. The response reuses the public ad summary shape."}},"/v1/brandtrackers/{brandtrackerId}/partnership-ads":{"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerPartnershipAds","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key. The adOrder value also accepts ad_order and ad-order aliases.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSort"}},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes for ad copy descriptions.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Comma-separated country include/exclude filters.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}},{"name":"partnerId","required":false,"in":"query","description":"Single partner identifier alias. It is merged with partnerIds when both are provided.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated brandtracker partnership ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No active workspace brandtracker matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker partnership ads","tags":["Brandtrackers"],"description":"Returns deduped Meta partnership ad groups for one active workspace brandtracker. This endpoint always filters to ads with a partner badge and reuses the public ad summary shape."}},"/v1/brandtrackers/{brandtrackerId}/partnership-ads/count":{"get":{"operationId":"PublicApiBrandtrackersController_getBrandtrackerPartnershipAdsCount","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes for ad copy descriptions.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Comma-separated country include/exclude filters.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}},{"name":"partnerId","required":false,"in":"query","description":"Single partner identifier alias. It is merged with partnerIds when both are provided.","schema":{"type":"string"}}],"responses":{"200":{"description":"Brandtracker partnership ads count response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerPartnershipAdsCountResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"No active workspace brandtracker matches the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Count brandtracker partnership ads","tags":["Brandtrackers"],"description":"Returns the deduped public ad group count matching the partnership ads list filters. This intentionally matches public list pagination semantics rather than the webapp raw active badge count."}},"/v1/brandtrackers/{brandtrackerId}/hooks":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getHooks","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional hook sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerHooksSortBy"}}],"responses":{"200":{"description":"Paginated brandtracker hooks analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerHooksResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker hooks","tags":["Brandtrackers"],"description":"Returns grouped hook analytics for the requested brandtracker using the authenticated workspace as the only access scope."}},"/v1/brandtrackers/{brandtrackerId}/transcripts":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getTranscripts","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional transcript sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTranscriptsSortBy"}}],"responses":{"200":{"description":"Paginated brandtracker transcripts analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTranscriptsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker transcripts","tags":["Brandtrackers"],"description":"Returns grouped transcript/script analytics for the requested brandtracker using the authenticated workspace as the only access scope."}},"/v1/brandtrackers/{brandtrackerId}/headlines":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getHeadlines","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional headline sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerHeadlinesSortBy"}}],"responses":{"200":{"description":"Paginated brandtracker headlines analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerHeadlinesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker headlines","tags":["Brandtrackers"],"description":"Returns grouped headline analytics for the requested brandtracker."}},"/v1/brandtrackers/{brandtrackerId}/ad-copies":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getAdCopies","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional ad copy sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdCopiesSortBy"}}],"responses":{"200":{"description":"Paginated brandtracker ad copies analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerAdCopiesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker ad copies","tags":["Brandtrackers"],"description":"Returns grouped ad copy analytics for the requested brandtracker."}},"/v1/brandtrackers/{brandtrackerId}/landing-pages":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getLandingPages","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional landing page sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPagesSortBy"}}],"responses":{"200":{"description":"Paginated brandtracker landing pages analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerLandingPagesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker landing pages","tags":["Brandtrackers"],"description":"Returns grouped landing page analytics for the requested brandtracker, including detected technologies when available."}},"/v1/brandtrackers/{brandtrackerId}/landing-pages/simple":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getLandingPagesSimple","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional normalized landing page sorting. Defaults to usageCount.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPagesSimpleSortBy"}}],"responses":{"200":{"description":"Paginated normalized brandtracker landing pages analytics response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerLandingPagesSimpleResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get normalized brandtracker landing pages","tags":["Brandtrackers"],"description":"Returns normalized/grouped landing page analytics for the requested brandtracker. Query strings, fragments, trailing slashes, and leading www. hostnames are ignored for grouping."}},"/v1/brandtrackers/{brandtrackerId}/creatives":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getCreatives","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional creatives sorting. Defaults to firstSeenAt.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerCreativesSortBy"}},{"name":"mediaType","required":false,"in":"query","description":"Optional media type filter. Defaults to all.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerCreativeMediaType"}}],"responses":{"200":{"description":"Paginated brandtracker creatives response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerCreativesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker creatives","tags":["Brandtrackers"],"description":"Returns paginated creative analytics for the requested brandtracker."}},"/v1/brandtrackers/{brandtrackerId}/partners":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getPartners","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"timePeriod","required":false,"in":"query","description":"Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"order","required":false,"in":"query","description":"Optional sort order. Defaults to desc.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.","schema":{"format":"date","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Optional partners sorting. Defaults to activeAds.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerPartnersSortBy"}},{"name":"cpm","required":false,"in":"query","description":"Optional CPM used to estimate spend from reach. Defaults to 9.","schema":{"minimum":0,"default":9,"type":"number"}}],"responses":{"200":{"description":"Paginated brandtracker partners response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerPartnersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker partners","tags":["Brandtrackers"],"description":"Returns paginated partnership analytics for the requested brandtracker."}},"/v1/brandtrackers/{brandtrackerId}/media-mix":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getMediaMix","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date (YYYY-MM-DD or latest). When provided, the mix is reconstructed for that date; otherwise it uses live active ads. Counts are deduped by ad before media buckets are calculated.","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"Brandtracker media mix response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerMediaMixResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker media mix","tags":["Brandtrackers"],"description":"Returns the media-format breakdown (image, video, dco, other) for the brandtracker's deduped currently active ads, or a deduped snapshot reconstruction when a snapshotDate is provided. activeAds equals the sum of the media buckets."}},"/v1/brandtrackers/{brandtrackerId}/demography":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getDemography","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"euOnly","required":false,"in":"query","description":"EU-only filter. This endpoint is fundamentally EU-scoped (the source data is the EU-only fb_page_reach_by_country table), so this defaults to true and is retained for forward compatibility.","schema":{"default":true,"type":"boolean"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date (YYYY-MM-DD or latest). The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.","schema":{"format":"date","type":"string"}},{"name":"timePeriod","required":false,"in":"query","description":"Optional time window. The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}}],"responses":{"200":{"description":"Brandtracker demography distributions response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerDemographyResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker demography","tags":["Brandtrackers"],"description":"Returns the EU country / age / gender reach distributions precomputed for the brandtracker. The underlying dataset is page-level and EU-only, so this endpoint is fundamentally EU-scoped."}},"/v1/brandtrackers/{brandtrackerId}/top-ads":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getTopAds","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"facebookPageId","required":false,"in":"query","description":"Optional Facebook page id belonging to this brandtracker. When omitted, the primary Facebook page is used.","schema":{"maxLength":64,"type":"string"}},{"name":"allFacebookPages","required":false,"in":"query","description":"When true, aggregate all selected Facebook pages. Current ranks are page-local, so ties across pages are expected. Cannot be combined with facebookPageId.","schema":{"default":false,"type":"boolean"}},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included.","schema":{"default":false,"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key for canonical current rankings. Use currentRank for the selected Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdsSortBy"}},{"name":"status","required":false,"in":"query","description":"Preferred activity filter. active returns active ads, inactive returns inactive ads, all returns both. When supplied, it takes precedence over includeInactive.","schema":{"$ref":"#/components/schemas/PublicApiAdsStatus"}},{"name":"includeInactive","required":false,"in":"query","deprecated":true,"description":"Deprecated. When status is omitted, includeInactive=true maps to status=all; ignored when status is supplied.","schema":{"default":false,"type":"boolean"}},{"name":"period","required":false,"in":"query","description":"Optional rolling top-ads period. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdsPeriod"}},{"name":"snapshotDate","required":false,"in":"query","deprecated":true,"description":"Deprecated compatibility parameter accepted but ignored by canonical top-ads current ranking. Use freshness/system endpoints for snapshot availability checks.","schema":{"oneOf":[{"type":"string","format":"date","example":"2026-04-20"},{"type":"string","enum":["latest"]}]}}],"responses":{"200":{"description":"Paginated brandtracker top ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTopAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get current ranked top ads","tags":["Brandtrackers"],"description":"Canonical current-ranking endpoint for a brandtracker. Use sortBy=currentRank for the current Facebook page rank, sortBy=reach/reachDelta1d/reachDelta7d/reachDelta30d for reach rankings, and sortBy=rankDelta7d/rankDelta14d/rankDelta30d for rank movers. period and snapshotDate are deprecated compatibility parameters and are ignored on this current-ranking path."}},"/v1/brandtrackers/{brandtrackerId}/ad-rank":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getAdRank","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"timeWindow","required":false,"in":"query","description":"Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdsTimeWindow"}},{"name":"sortBy","required":false,"in":"query","description":"Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdsSortBy"}},{"name":"snapshotDate","required":false,"in":"query","deprecated":true,"description":"Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.","schema":{"format":"date","type":"string"}},{"name":"maxCurrentRank","required":false,"in":"query","description":"Optional maximum current rank filter. Only ads at or above this current rank are returned.","schema":{"minimum":1,"type":"integer"}},{"name":"minRankDelta","required":false,"in":"query","description":"Minimum positive rank improvement required for an ad to be returned. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}}],"responses":{"200":{"description":"Paginated brandtracker ad rank response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerScalingAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker ad rank compatibility data","tags":["Brandtrackers"],"description":"Compatibility endpoint for clients that still call /ad-rank. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty."}},"/v1/brandtrackers/{brandtrackerId}/scaling-ads":{"get":{"operationId":"PublicApiBrandtrackerInsightsController_getScalingAds","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return. Defaults to 20.","schema":{"minimum":1,"maximum":50,"default":20,"type":"integer"}},{"name":"timeWindow","required":false,"in":"query","description":"Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdsTimeWindow"}},{"name":"sortBy","required":false,"in":"query","description":"Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdsSortBy"}},{"name":"snapshotDate","required":false,"in":"query","deprecated":true,"description":"Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.","schema":{"format":"date","type":"string"}},{"name":"maxCurrentRank","required":false,"in":"query","description":"Optional maximum current rank filter. Only ads at or above this current rank are returned.","schema":{"minimum":1,"type":"integer"}},{"name":"minRankDelta","required":false,"in":"query","description":"Minimum positive rank improvement required for an ad to be returned. Defaults to 1.","schema":{"minimum":1,"default":1,"type":"integer"}}],"responses":{"200":{"description":"Paginated brandtracker scaling ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerScalingAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker scaling ads compatibility data","tags":["Brandtrackers"],"description":"Legacy compatibility endpoint for clients that still call /scaling-ads. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty."}},"/v1/brandtrackers/{brandtrackerId}/overview":{"get":{"operationId":"PublicApiBrandtrackerOverviewController_getOverview","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"euOnly","required":false,"in":"query","description":"Optional EU-only filter forwarded to graph, media mix, landing pages, and top ads sections where supported.","schema":{"default":false,"type":"boolean"}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date for dashboard time travel. Use YYYY-MM-DD or latest.","schema":{"oneOf":[{"type":"string","format":"date","example":"2026-04-20"},{"type":"string","enum":["latest"]}]}},{"name":"cpm","required":false,"in":"query","description":"CPM used to estimate spend in the graph section.","schema":{"minimum":0.01,"maximum":10000,"default":9,"type":"number"}},{"name":"timeSeriesGranularity","required":false,"in":"query","description":"Bucket size for the graph section. Defaults to daily.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesGranularity"}},{"name":"timeSeriesStartDate","required":false,"in":"query","description":"Inclusive graph start date. Cannot be combined with timeSeriesPeriod.","schema":{"format":"date","type":"string"}},{"name":"timeSeriesEndDate","required":false,"in":"query","description":"Inclusive graph end date. Cannot be combined with timeSeriesPeriod.","schema":{"format":"date","type":"string"}},{"name":"timeSeriesPeriod","required":false,"in":"query","description":"Optional rolling window for the graph section. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with timeSeriesStartDate or timeSeriesEndDate; snapshotDate may anchor the window.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesPeriod"}},{"name":"landingPagesTimePeriod","required":false,"in":"query","description":"Time window for top landing pages. Defaults to live for dashboard-style current overview.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsTimePeriod"}},{"name":"landingPagesLimit","required":false,"in":"query","description":"Maximum number of top landing pages to return. Defaults to 5.","schema":{"minimum":1,"maximum":20,"default":5,"type":"integer"}},{"name":"topAdsLimit","required":false,"in":"query","description":"Maximum number of top ads to return. Defaults to 5.","schema":{"minimum":1,"maximum":20,"default":5,"type":"integer"}},{"name":"adsPreviewLimit","required":false,"in":"query","description":"Maximum number of ads preview items to return. Defaults to 10.","schema":{"minimum":1,"maximum":50,"default":10,"type":"integer"}},{"name":"topAdsSortBy","required":false,"in":"query","description":"Optional top ads sorting. Defaults to reach when euOnly=true, otherwise daysRunning.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdsSortBy"}},{"name":"topAdsPeriod","required":false,"in":"query","description":"Optional top ads period. Supports `today`, `yesterday`, `last1d`, `last7d`, `last14d`, `last30d`, and `total`. Defaults to `total`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdsPeriod"}}],"responses":{"200":{"description":"Brandtracker overview response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerOverviewResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker overview","tags":["Brandtrackers"],"description":"Returns a dashboard-style Brandtracker overview combining graph, media mix, top landing pages, top ads, and ads preview sections. The graph accepts timeSeriesPeriod for rolling windows or timeSeriesStartDate/timeSeriesEndDate for explicit ranges; do not combine them."}},"/v1/brandtrackers/{brandtrackerId}/timeline":{"get":{"operationId":"PublicApiBrandtrackerTimelineController_getTimeline","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"integer"}},{"name":"sortBy","required":false,"in":"query","description":"Sort key for this request. Allowed values: `newest`, `createdAt`, `longestRunning`, `reach`, `duplicates`, `adOrder`, `relevance`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSort"}},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partners","required":false,"in":"query","description":"When true, keep only partnership ads. When false, keep only non-partnership ads.","schema":{"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}},{"name":"startedAfter","required":false,"in":"query","description":"Inclusive ad start-date lower bound.","schema":{"format":"date","type":"string"}},{"name":"startedBefore","required":false,"in":"query","description":"Inclusive ad start-date upper bound.","schema":{"format":"date","type":"string"}},{"name":"lastSeenAfter","required":false,"in":"query","description":"Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}},{"name":"lastSeenBefore","required":false,"in":"query","description":"Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"Paginated brandtracker timeline response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTimelineResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker timeline ads","tags":["Brandtrackers"],"description":"Returns timeline-ready Meta ads for one active workspace brandtracker resolved from brandtracker.id. Timeline membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date."}},"/v1/brandtrackers/{brandtrackerId}/timeline/metadata":{"get":{"operationId":"PublicApiBrandtrackerTimelineController_getTimelineMetadata","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partners","required":false,"in":"query","description":"When true, keep only partnership ads. When false, keep only non-partnership ads.","schema":{"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"type":"integer"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"type":"integer"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}},{"name":"startedAfter","required":false,"in":"query","description":"Inclusive ad start-date lower bound.","schema":{"format":"date","type":"string"}},{"name":"startedBefore","required":false,"in":"query","description":"Inclusive ad start-date upper bound.","schema":{"format":"date","type":"string"}},{"name":"lastSeenAfter","required":false,"in":"query","description":"Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}},{"name":"lastSeenBefore","required":false,"in":"query","description":"Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"Brandtracker timeline metadata response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTimelineMetadataResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker timeline metadata","tags":["Brandtrackers"],"description":"Returns total count and date bounds for the same filter membership used by the brandtracker timeline endpoint."}},"/v1/brandtrackers/{brandtrackerId}/testing":{"get":{"operationId":"PublicApiBrandtrackerTestingController_getTesting","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Batch page number. Pagination is by distinct ad start-date batches.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Number of distinct start-date batches to return. Each batch returns at most 20 ads.","schema":{"minimum":1,"maximum":50,"default":25,"type":"integer"}},{"name":"status","required":false,"in":"query","description":"Status filter for this request. Allowed values: `all`, `active`, `inactive`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsStatus"}},{"name":"mediaType","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `all`, `image`, `video`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsMediaType"}},{"name":"keywords","required":false,"in":"query","description":"Keyword search terms. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"keywordMode","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsKeywordMode"}},{"name":"createdAfter","required":false,"in":"query","schema":{"format":"date-time","nullable":true,"type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"format":"date-time","nullable":true,"type":"string"}},{"name":"minDaysRunning","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxDaysRunning","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"minDuplicates","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxDuplicates","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"landingPages","required":false,"in":"query","description":"Landing page URLs. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adLanguage","required":false,"in":"query","description":"Ad languages. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"cta","required":false,"in":"query","description":"Call-to-action labels. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCopyHashes","required":false,"in":"query","description":"12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"adCountries","required":false,"in":"query","description":"Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.","schema":{"example":"US=include,FR=exclude","type":"string"}},{"name":"mainCountries","required":false,"in":"query","description":"Main ad countries. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"euOnly","required":false,"in":"query","description":"When true, keep only ads flagged as EU ads.","schema":{"type":"boolean"}},{"name":"partners","required":false,"in":"query","description":"When true, keep only partnership ads. When false, keep only non-partnership ads.","schema":{"nullable":true,"type":"boolean"}},{"name":"partnerIds","required":false,"in":"query","description":"Partner identifiers. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"type":"string"}}},{"name":"minReach","required":false,"in":"query","description":"Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxReach","required":false,"in":"query","description":"Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to convert spend filters into reach thresholds.","schema":{"minimum":0.01,"default":9,"type":"number"}},{"name":"minSpend","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxSpend","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"spendPeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"minSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxSpendPerPage","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"spendPerPagePeriod","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `total`, `last24h`, `last7d`, `last30d`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSpendPeriod"}},{"name":"hideLowReach","required":false,"in":"query","description":"When true, hides ads flagged as low reach.","schema":{"type":"boolean"}},{"name":"minAge","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxAge","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"sex","required":false,"in":"query","description":"Enum value accepted by this request. Allowed values: `men`, `women`, `all`.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsSex"}},{"name":"minFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxFacebookLikes","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"minInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxInstagramFollowers","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"minVideoDuration","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxVideoDuration","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"minDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"maxDescriptionLength","required":false,"in":"query","schema":{"minimum":0,"nullable":true,"type":"number"}},{"name":"linkedDomain","required":false,"in":"query","description":"Linked domain filter. URLs are normalized to their hostname before validation.","schema":{"example":"example.com","type":"string"}},{"name":"growthRank","required":false,"in":"query","description":"Rank trend filters. Repeated query params and comma-separated values are both accepted.","schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdsGrowthRank"}}},{"name":"snapshotDate","required":false,"in":"query","description":"Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.","schema":{"format":"date","type":"string"}},{"name":"startedAfter","required":false,"in":"query","description":"Inclusive ad start-date lower bound.","schema":{"format":"date","type":"string"}},{"name":"startedBefore","required":false,"in":"query","description":"Inclusive ad start-date upper bound.","schema":{"format":"date","type":"string"}},{"name":"lastSeenAfter","required":false,"in":"query","description":"Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}},{"name":"lastSeenBefore","required":false,"in":"query","description":"Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"Paginated brandtracker testing response. Pagination is by start-date batches and the response includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTestingResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List brandtracker creative testing batches","tags":["Brandtrackers"],"description":"Returns creative-testing batches grouped by ad start date for one active workspace brandtracker resolved from brandtracker.id. Testing membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date. To keep response size and metering bounded, each batch returns at most 20 ads and exposes truncation metadata."}},"/v1/brandtrackers/{brandtrackerId}/time-series":{"get":{"operationId":"PublicApiBrandtrackerTimeSeriesController_getTimeSeries","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"granularity","required":false,"in":"query","description":"Bucket size for the returned graph data. Defaults to daily.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesGranularity"}},{"name":"startDate","required":false,"in":"query","description":"Inclusive start date. Defaults to 365 days before the effective end date. Cannot be combined with period.","schema":{"format":"date","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Inclusive end date. Defaults to today unless snapshotDate is provided. Cannot be combined with period.","schema":{"format":"date","type":"string"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date. When provided with period, it anchors the rolling window; otherwise it is used as the effective end date.","schema":{"format":"date","type":"string"}},{"name":"period","required":false,"in":"query","description":"Optional rolling window for the time-series. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with startDate or endDate; snapshotDate may anchor the window.","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesPeriod"}},{"name":"euOnly","required":false,"in":"query","description":"When true, only EU-classified ads are counted for adsLaunched.","schema":{"default":false,"type":"boolean"}},{"name":"cpm","required":false,"in":"query","description":"CPM used to estimate spend from EU impression deltas.","schema":{"minimum":0.01,"maximum":10000,"default":9,"type":"number"}}],"responses":{"200":{"description":"Brandtracker time-series response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerTimeSeriesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker time-series","tags":["Brandtrackers"],"description":"Returns graph-ready Brandtracker time-series for ads launched, live ads history, and EU impression/spend deltas. Use period for rolling windows, or startDate/endDate for explicit ranges; do not combine period with date params."}},"/v1/brandtrackers/{brandtrackerId}/ad-copy-evolution":{"get":{"operationId":"PublicApiBrandtrackerEvolutionController_getAdCopyEvolution","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number for global mode. Exact mode always returns at most one series.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Number of series to return in global mode. Exact mode costs and returns one series.","schema":{"minimum":1,"maximum":25,"default":10,"type":"integer"}},{"name":"startDate","required":false,"in":"query","description":"Inclusive start date. Defaults to 365 days before the effective end date.","schema":{"format":"date","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Inclusive end date. Defaults to today unless snapshotDate is provided.","schema":{"format":"date","type":"string"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date. When provided, it is used as the effective end date.","schema":{"format":"date","type":"string"}},{"name":"adCopy","required":false,"in":"query","description":"Exact ad copy text to return as a single evolution series. Omit for global mode.","schema":{"maxLength":5000,"type":"string"}}],"responses":{"200":{"description":"Paginated ad copy evolution response. Pagination is by distinct ad copy series and the response includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerAdCopyEvolutionResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker ad copy evolution","tags":["Brandtrackers"],"description":"Returns graph-ready ad copy evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide adCopy for exact single-text mode, or omit it to page through bounded global series ranked by active ads."}},"/v1/brandtrackers/{brandtrackerId}/headline-evolution":{"get":{"operationId":"PublicApiBrandtrackerEvolutionController_getHeadlineEvolution","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number for global mode. Exact mode always returns at most one series.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Number of series to return in global mode. Exact mode costs and returns one series.","schema":{"minimum":1,"maximum":25,"default":10,"type":"integer"}},{"name":"startDate","required":false,"in":"query","description":"Inclusive start date. Defaults to 365 days before the effective end date.","schema":{"format":"date","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Inclusive end date. Defaults to today unless snapshotDate is provided.","schema":{"format":"date","type":"string"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date. When provided, it is used as the effective end date.","schema":{"format":"date","type":"string"}},{"name":"headline","required":false,"in":"query","description":"Exact headline text to return as a single evolution series. Omit for global mode.","schema":{"maxLength":1000,"type":"string"}}],"responses":{"200":{"description":"Paginated headline evolution response. Pagination is by distinct headline series and the response includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerHeadlineEvolutionResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker headline evolution","tags":["Brandtrackers"],"description":"Returns graph-ready headline evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide headline for exact single-text mode, or omit it to page through bounded global series ranked by active ads."}},"/v1/brandtrackers/{brandtrackerId}/landing-page-evolution":{"get":{"operationId":"PublicApiBrandtrackerEvolutionController_getLandingPageEvolution","parameters":[{"name":"brandtrackerId","required":true,"in":"path","schema":{"type":"string"},"description":"Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists."},{"name":"page","required":false,"in":"query","description":"Pagination page number for global mode. Exact mode always returns at most one series.","schema":{"minimum":1,"default":1,"type":"integer"}},{"name":"limit","required":false,"in":"query","description":"Number of series to return in global mode. Exact mode costs and returns one series.","schema":{"minimum":1,"maximum":25,"default":10,"type":"integer"}},{"name":"startDate","required":false,"in":"query","description":"Inclusive start date. Defaults to 365 days before the effective end date.","schema":{"format":"date","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Inclusive end date. Defaults to today unless snapshotDate is provided.","schema":{"format":"date","type":"string"}},{"name":"snapshotDate","required":false,"in":"query","description":"Optional snapshot date. When provided, it is used as the effective end date.","schema":{"format":"date","type":"string"}},{"name":"landingPage","required":false,"in":"query","description":"Exact landing page URL to return as a single evolution series. Omit for global mode.","schema":{"maxLength":2048,"type":"string"}}],"responses":{"200":{"description":"Paginated landing page evolution response. Pagination is by distinct landing page series and the response includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetBrandtrackerLandingPageEvolutionResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"The brandtracker could not be found in the authenticated workspace or is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get brandtracker landing page evolution","tags":["Brandtrackers"],"description":"Returns graph-ready landing page evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide landingPage for exact single-page mode, or omit it to page through bounded global series ranked by active ads."}},"/v1/boards":{"get":{"operationId":"PublicApiBoardsController_listBoards","parameters":[{"name":"scope","required":false,"in":"query","schema":{"default":"workspace","type":"string","enum":["workspace","personal"]}},{"name":"state","required":false,"in":"query","schema":{"default":"active","type":"string","enum":["active","archived"]}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["folder","collection"]}},{"name":"surface","required":false,"in":"query","schema":{"type":"string","enum":["ads","shops","landing","emails","products","advertisers"]}},{"name":"parentBoardId","required":false,"in":"query","schema":{"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","type":"string"}},{"name":"rootOnly","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardsListResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List boards","tags":["Boards"]},"post":{"operationId":"PublicApiBoardsController_createBoard","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiBoardBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a board","tags":["Boards"]}},"/v1/boards/{boardId}":{"get":{"operationId":"PublicApiBoardsController_getBoard","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get a board","tags":["Boards"]},"patch":{"operationId":"PublicApiBoardsController_updateBoard","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UpdatePublicApiBoardBodyDto"},{"anyOf":[{"required":["name"]},{"required":["description"]},{"required":["visibility"]}]}]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Update a board","tags":["Boards"]},"delete":{"description":"Archives the board subtree. The operation is reversible through the restore endpoint.","operationId":"PublicApiBoardsController_archiveBoard","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Archive a board","tags":["Boards"]}},"/v1/boards/{boardId}/parent":{"patch":{"operationId":"PublicApiBoardsController_moveBoard","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovePublicApiBoardBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Move a board","tags":["Boards"]}},"/v1/boards/{boardId}/restore":{"post":{"operationId":"PublicApiBoardsController_restoreBoard","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Restore an archived board","tags":["Boards"]}},"/v1/boards/{boardId}/items":{"get":{"operationId":"PublicApiBoardsController_listBoardItems","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardItemsListResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List board item references","tags":["Boards"]},"post":{"operationId":"PublicApiBoardsController_addBoardItem","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPublicApiBoardItemBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiAddBoardItemResponseDto"}}}},"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiAddBoardItemResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Add an item to a board","tags":["Boards"]}},"/v1/boards/{boardId}/items/{itemId}/move":{"post":{"operationId":"PublicApiBoardsController_moveBoardItem","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"itemId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovePublicApiBoardItemBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardItemResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Move a board item","tags":["Boards"]}},"/v1/boards/{boardId}/items/{itemId}":{"delete":{"operationId":"PublicApiBoardsController_removeBoardItem","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"itemId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveBoardItemResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Remove a board item","tags":["Boards"]}},"/v1/boards/{boardId}/share-links":{"post":{"operationId":"PublicApiBoardsController_createBoardShareLink","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiBoardShareLinkResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"`product_entitlement_required` when the workspace plan is not Pro, Business or Agency (`details.resourceFamily` = `boards`); `forbidden` with `details.reason` = `workspace_banned` when the workspace is banned; `forbidden` when the credential cannot reach or change the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a board share link","tags":["Boards"]}},"/v1/favorites/ads":{"post":{"deprecated":true,"description":"Saves an ad to the requested workspace or delegated-user favorites scope. Existing favorites are returned idempotently without creating an audit mutation event. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_addFavoriteAd","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPublicApiFavoriteAdBodyDto"}}}},"responses":{"200":{"description":"Favorite ad mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteAdMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Add a favorite ad","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteAds","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"folderId","required":false,"in":"query","description":"Optional ads folder identifier. This is the folder id (board id, or migrated V2 folder UUID). When provided, only favorites saved in that folder are returned.","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}}],"responses":{"200":{"description":"Paginated favorite ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite ads","tags":["Favorites"]}},"/v1/favorites/ads/saved/{favoriteId}/folder":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_moveSavedFavoriteAd","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveSavedPublicApiFavoriteAdBodyDto"}}}},"responses":{"200":{"description":"Saved favorite ad move response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMoveSavedFavoriteAdResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Move a saved favorite ad","tags":["Favorites"]}},"/v1/favorites/ads/saved/{favoriteId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteSavedFavoriteAd","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"responses":{"200":{"description":"Saved favorite ad removal response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteAdResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a saved favorite ad","tags":["Favorites"]}},"/v1/favorites/ads/{adId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_removeFavoriteAd","parameters":[{"name":"adId","required":true,"in":"path","schema":{"type":"string"},"description":"Composite public ad identifier, for example facebook_123 or tiktok_123."},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."},{"name":"folderId","required":false,"in":"query","description":"Favorite ads folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's \"Unsorted\" board.","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}}],"responses":{"200":{"description":"Favorite ad removal response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteAdResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Remove a favorite ad","tags":["Favorites"]}},"/v1/favorites/ads/folders":{"post":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_createFavoriteAdsFolder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiFavoriteAdsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite ad folder mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a favorite ad folder","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteAdsFolders","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"parentId","required":false,"in":"query","description":"Optional parent folder id (board id, or migrated V2 folder UUID). When provided, only direct children of that folder are returned.","schema":{"example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","type":"string"}},{"name":"rootOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"When true, returns only root folders. Cannot be combined with parentId."}],"responses":{"200":{"description":"Paginated favorite ad folders response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteAdsFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite ad folders","tags":["Favorites"]}},"/v1/favorites/ads/folders/reorder":{"patch":{"deprecated":true,"description":"Boards have no manual order: the folders are validated and echoed back in the requested order, but no order is persisted. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_reorderFavoriteAdsFolders","parameters":[{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderPublicApiFavoriteAdsFoldersBodyDto"}}}},"responses":{"200":{"description":"Favorite ad folders reorder response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiReorderFavoriteAdsFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Reorder favorite ad folders","tags":["Favorites"]}},"/v1/favorites/ads/folders/{folderId}/share":{"post":{"deprecated":true,"description":"Each call creates a new board share link. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_createFavoriteAdsFolderShare","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"responses":{"200":{"description":"Public favorite ad folder share URL response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateFavoriteAdsFolderShareResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a favorite ad folder share URL","tags":["Favorites"]}},"/v1/favorites/ads/folders/{folderId}/visibility":{"patch":{"deprecated":true,"description":"organization shares the board with the workspace; private is only allowed for folders created by the delegated user. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_setFavoriteAdsFolderVisibility","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPublicApiFavoriteAdsFolderVisibilityBodyDto"}}}},"responses":{"200":{"description":"Favorite ad folder visibility response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Set favorite ad folder visibility","tags":["Favorites"]}},"/v1/favorites/ads/folders/{folderId}":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_updateFavoriteAdsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicApiFavoriteAdsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite ad folder mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Rename or move a favorite ad folder","tags":["Favorites"]},"delete":{"deprecated":true,"description":"The folder's board is archived, not destroyed: restore it with POST /v1/boards/{boardId}/restore. With move_items_to_root, items go to the scope's \"Unsorted\" board. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteFavoriteAdsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePublicApiFavoriteAdsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite ad folder delete response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteAdsFolderResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a favorite ad folder","tags":["Favorites"]}},"/v1/favorites/shops":{"post":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_addFavoriteShop","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPublicApiFavoriteShopBodyDto"}}}},"responses":{"200":{"description":"Favorite shop mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteShopMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Add a favorite shop","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteShops","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"folderId","required":false,"in":"query","description":"Optional shops folder identifier. When provided, only favorites saved in that folder are returned.","schema":{"example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","type":"string"}}],"responses":{"200":{"description":"Paginated favorite shops response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteShopsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite shops","tags":["Favorites"]}},"/v1/favorites/shops/saved/{favoriteId}/folder":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_moveSavedFavoriteShop","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveSavedPublicApiFavoriteShopBodyDto"}}}},"responses":{"200":{"description":"Saved favorite shop move response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMoveSavedFavoriteShopResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Move a saved favorite shop","tags":["Favorites"]}},"/v1/favorites/shops/saved/{favoriteId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteSavedFavoriteShop","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"responses":{"200":{"description":"Saved favorite shop removal response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteShopResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a saved favorite shop","tags":["Favorites"]}},"/v1/favorites/shops/{websiteId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_removeFavoriteShop","parameters":[{"name":"websiteId","required":true,"in":"path","schema":{"type":"string","format":"uuid"},"description":"Public website/shop identifier."},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."},{"name":"folderId","required":false,"in":"query","description":"Favorite shops folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's \"Unsorted\" board.","schema":{"example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","type":"string"}}],"responses":{"200":{"description":"Favorite shop removal response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteShopResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Remove a favorite shop by website id","tags":["Favorites"]}},"/v1/favorites/shops/folders":{"post":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_createFavoriteShopsFolder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiFavoriteShopsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite shop folder mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a favorite shop folder","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteShopsFolders","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated favorite shop folders response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteShopsFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite shop folders","tags":["Favorites"]}},"/v1/favorites/shops/folders/{folderId}/visibility":{"patch":{"deprecated":true,"description":"organization shares the board with the workspace; private is only allowed for folders created by the delegated user. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_setFavoriteShopsFolderVisibility","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPublicApiFavoriteShopsFolderVisibilityBodyDto"}}}},"responses":{"200":{"description":"Favorite shop folder visibility response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Set favorite shop folder visibility","tags":["Favorites"]}},"/v1/favorites/shops/folders/{folderId}":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_updateFavoriteShopsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicApiFavoriteShopsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite shop folder mutation response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Rename a favorite shop folder","tags":["Favorites"]},"delete":{"deprecated":true,"description":"The folder's board is archived, not destroyed: restore it with POST /v1/boards/{boardId}/restore. With move_items_to_root, items go to the scope's \"Unsorted\" board. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteFavoriteShopsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePublicApiFavoriteShopsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite shop folder delete response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteShopsFolderResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a favorite shop folder","tags":["Favorites"]}},"/v1/favorites/emails":{"post":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_addFavoriteEmail","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPublicApiFavoriteEmailBodyDto"}}}},"responses":{"200":{"description":"Favorite email mutation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteEmailMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Add or update a favorite email","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteEmails","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"folderId","required":false,"in":"query","description":"Optional emails folder id (board id, or migrated V2 folder UUID). When provided, only favorites saved in that folder are returned.","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}}],"responses":{"200":{"description":"Paginated favorite emails response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteEmailsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite emails","tags":["Favorites"]}},"/v1/favorites/emails/saved/{favoriteId}/folder":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_moveSavedFavoriteEmail","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveSavedPublicApiFavoriteEmailBodyDto"}}}},"responses":{"200":{"description":"Saved favorite email move response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMoveSavedFavoriteEmailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Move a saved favorite email","tags":["Favorites"]}},"/v1/favorites/emails/saved/{favoriteId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteSavedFavoriteEmail","parameters":[{"name":"favoriteId","required":true,"in":"path","description":"Saved favorite id, which is the board item id.","schema":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b"}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"responses":{"200":{"description":"Saved favorite email removal response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteEmailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a saved favorite email","tags":["Favorites"]}},"/v1/favorites/emails/folders":{"post":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_createFavoriteEmailsFolder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicApiFavoriteEmailsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite email folder mutation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Create a favorite email folder","tags":["Favorites"]},"get":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_getFavoriteEmailsFolders","parameters":[{"name":"scope","required":true,"in":"query","description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated favorite email folders response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetFavoriteEmailsFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"List favorite email folders","tags":["Favorites"]}},"/v1/favorites/emails/folders/reorder":{"patch":{"deprecated":true,"description":"Boards have no manual order: the folders are validated and echoed back in the requested order, but no order is persisted. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_reorderFavoriteEmailsFolders","parameters":[{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderPublicApiFavoriteEmailsFoldersBodyDto"}}}},"responses":{"200":{"description":"Favorite email folders reorder response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiReorderFavoriteEmailsFoldersResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Reorder favorite email folders","tags":["Favorites"]}},"/v1/favorites/emails/folders/{folderId}/visibility":{"patch":{"deprecated":true,"description":"organization shares the board with the workspace; private is only allowed for folders created by the delegated user. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_setFavoriteEmailsFolderVisibility","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPublicApiFavoriteEmailsFolderVisibilityBodyDto"}}}},"responses":{"200":{"description":"Favorite email folder visibility response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Set favorite email folder visibility","tags":["Favorites"]}},"/v1/favorites/emails/folders/{folderId}":{"patch":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_updateFavoriteEmailsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicApiFavoriteEmailsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite email folder mutation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderMutationResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Rename or move a favorite email folder","tags":["Favorites"]},"delete":{"deprecated":true,"description":"The folder's board is archived, not destroyed: restore it with POST /v1/boards/{boardId}/restore. With move_items_to_root, items go to the scope's \"Unsorted\" board. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_deleteFavoriteEmailsFolder","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePublicApiFavoriteEmailsFolderBodyDto"}}}},"responses":{"200":{"description":"Favorite email folder delete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteEmailsFolderResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Delete a favorite email folder","tags":["Favorites"]}},"/v1/favorites/emails/{emailId}":{"delete":{"deprecated":true,"description":"Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's \"Unsorted\" board.","operationId":"PublicApiFavoritesController_removeFavoriteEmail","parameters":[{"name":"emailId","required":true,"in":"path","schema":{"type":"integer","minimum":1},"description":"Public email identifier. To delete a saved favorite row by favorite_emails.uuid, use DELETE /v1/favorites/emails/saved/:favoriteId."},{"name":"scope","required":true,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiFavoritesScope"},"description":"Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope."},{"name":"folderId","required":false,"in":"query","description":"Favorite emails folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's \"Unsorted\" board.","schema":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: a board id, or the UUID of a V2 folder migrated to a board."}}],"responses":{"200":{"description":"Favorite email removal response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteEmailResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Remove a favorite email by email id","tags":["Favorites"]}},"/v1/workspace/top-ads":{"get":{"description":"Canonical current-ranking endpoint across active workspace brandtrackers in a single metered request. Each returned row is explicitly nested as { brandtracker, ad, metrics }. Billing remains proportional to requested/returned row count (limit/result length), not brandtracker count. Use sortBy=currentRank for current Facebook page rank, sortBy=reach/reachDelta1d/reachDelta7d/reachDelta30d for reach rankings, and sortBy=rankDelta7d/rankDelta14d/rankDelta30d for rank movers. period and snapshotDate are deprecated compatibility parameters and are ignored on this current-ranking path.","operationId":"PublicApiWorkspaceTopAdsController_getWorkspaceTopAds","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Pagination page number. Defaults to 1."},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace top ads to return. Must be <= 100."},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdsSortBy"},"description":"Sort key for canonical current rankings. Use currentRank for current Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings."},{"name":"includeInactive","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"When true, include inactive ads where supported. Defaults to false."},{"name":"period","required":false,"in":"query","description":"Optional rolling workspace top-ads period. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.","schema":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsPeriod"}},{"name":"snapshotDate","required":false,"in":"query","deprecated":true,"description":"Deprecated compatibility parameter accepted but ignored by canonical workspace top-ads current ranking. Use freshness/system endpoints for snapshot availability checks.","schema":{"oneOf":[{"type":"string","format":"date","example":"2026-04-20"},{"type":"string","enum":["latest"]}]}}],"responses":{"200":{"description":"Paginated workspace top ads response where each data row is { brandtracker, ad, metrics }. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceTopAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get current ranked workspace top ads","tags":["Workspace"]}},"/v1/workspace/hooks":{"get":{"operationId":"PublicApiWorkspaceAggregatesController_getHooks","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace aggregate rows to return. Must be <= 100."},{"name":"brandtrackerIds","required":false,"in":"query","description":"Optional comma-separated or repeated public brandtracker ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"folderIds","required":false,"in":"query","description":"Optional comma-separated or repeated workspace brandtracker folder ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"order","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerHooksSortBy"}}],"responses":{"200":{"description":"Paginated workspace hooks response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceHooksResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get workspace hooks","tags":["Workspace"],"description":"Returns hook analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row."}},"/v1/workspace/ad-copies":{"get":{"operationId":"PublicApiWorkspaceAggregatesController_getAdCopies","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace aggregate rows to return. Must be <= 100."},{"name":"brandtrackerIds","required":false,"in":"query","description":"Optional comma-separated or repeated public brandtracker ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"folderIds","required":false,"in":"query","description":"Optional comma-separated or repeated workspace brandtracker folder ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"order","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdCopiesSortBy"}}],"responses":{"200":{"description":"Paginated workspace ad copies response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceAdCopiesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get workspace ad copies","tags":["Workspace"],"description":"Returns ad copy analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row."}},"/v1/workspace/landing-pages":{"get":{"operationId":"PublicApiWorkspaceAggregatesController_getLandingPages","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace aggregate rows to return. Must be <= 100."},{"name":"brandtrackerIds","required":false,"in":"query","description":"Optional comma-separated or repeated public brandtracker ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"folderIds","required":false,"in":"query","description":"Optional comma-separated or repeated workspace brandtracker folder ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"order","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsSortOrder"}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPagesSortBy"}}],"responses":{"200":{"description":"Paginated workspace landing pages response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceLandingPagesResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get workspace landing pages","tags":["Workspace"],"description":"Returns landing page analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row."}},"/v1/workspace/scaling-ads":{"get":{"operationId":"PublicApiWorkspaceAggregatesController_getScalingAds","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace aggregate rows to return. Must be <= 100."},{"name":"brandtrackerIds","required":false,"in":"query","description":"Optional comma-separated or repeated public brandtracker ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"folderIds","required":false,"in":"query","description":"Optional comma-separated or repeated workspace brandtracker folder ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"period","required":false,"in":"query","description":"Optional rolling period for workspace scaling ads. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.","schema":{"$ref":"#/components/schemas/PublicApiWorkspaceAggregatePeriod"}},{"name":"snapshotDate","required":false,"in":"query","deprecated":true,"description":"Deprecated compatibility parameter accepted but ignored on the ES-backed workspace scaling compatibility path. Use freshness/system endpoints for snapshot availability checks.","schema":{"oneOf":[{"type":"string","format":"date","example":"2026-04-20"},{"type":"string","enum":["latest"]}]}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdsSortBy"}},{"name":"maxCurrentRank","required":false,"in":"query","schema":{"type":"integer","minimum":1}},{"name":"minRankDelta","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Paginated workspace scaling ads response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceScalingAdsResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get workspace scaling ads compatibility data","tags":["Workspace"],"description":"Legacy compatibility endpoint for clients that still call /workspace/scaling-ads. Prefer /v1/workspace/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; period and snapshotDate are deprecated and ignored on the ES-backed path, and trajectory may be empty. One credit is charged per returned row."}},"/v1/workspace/media-mix":{"get":{"operationId":"PublicApiWorkspaceAggregatesController_getMediaMix","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of workspace aggregate rows to return. Must be <= 100."},{"name":"brandtrackerIds","required":false,"in":"query","description":"Optional comma-separated or repeated public brandtracker ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"folderIds","required":false,"in":"query","description":"Optional comma-separated or repeated workspace brandtracker folder ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"euOnly","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"Optional EU-only filter. When true, only EU-classified Facebook ads are included."},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PublicApiWorkspaceMediaMixSortBy"}}],"responses":{"200":{"description":"Paginated workspace media mix response. The response also includes the X-Request-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiGetWorkspaceMediaMixResponseDto"}}}},"401":{"description":"Authentication failed. Possible error codes: missing_api_key, invalid_api_key, credential_not_found, credential_revoked, credential_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"403":{"description":"Workspace or delegated access rejected. Possible error codes: workspace_public_api_disabled, workspace_public_api_suspended, delegated_user_access_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"500":{"description":"Unexpected public API failure. Possible error code: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}},"503":{"description":"Public auth provider is temporarily unavailable. Possible error code: auth_provider_unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponseDto"}}}}},"security":[{"publicApiBearer":[]}],"summary":"Get workspace media mix","tags":["Workspace"],"description":"Returns media mix rows across active workspace brandtrackers in one metered request. One credit is charged per returned row."}},"/v1/mcp":{"post":{"operationId":"PublicApiMcpController_handleMcpRequest","parameters":[],"responses":{"200":{"description":""}}},"head":{"operationId":"PublicApiMcpController_handleMcpHeadRequest","parameters":[],"responses":{"200":{"description":""}}},"get":{"operationId":"PublicApiMcpController_handleMcpGetRequest","parameters":[],"responses":{"405":{"description":""}}},"delete":{"operationId":"PublicApiMcpController_handleMcpDeleteRequest","parameters":[],"responses":{"405":{"description":""}}}},"/.well-known/oauth-protected-resource/v1/mcp":{"get":{"operationId":"PublicApiMcpMetadataController_getProtectedResourceMetadata","parameters":[],"responses":{"200":{"description":""}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"PublicApiMcpMetadataController_getProtectedResourceMetadataRoot","parameters":[],"responses":{"200":{"description":""}}}},"/.well-known/oauth-authorization-server/v1/mcp":{"get":{"operationId":"PublicApiMcpAuthServerMetadataController_getAuthorizationServerMetadata","parameters":[],"responses":{"200":{"description":""}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"PublicApiMcpAuthServerMetadataController_getAuthorizationServerMetadataRoot","parameters":[],"responses":{"200":{"description":""}}}}},"info":{"title":"Trendtrack Public API","description":"Generated OpenAPI contract for the public bootstrap only. This spec documents the current /v1 shell endpoints and excludes the internal /api/v1 backend routes.","version":"v1","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"publicApiBearer":{"scheme":"bearer","bearerFormat":"API key","type":"http","description":"Provide a Trendtrack Public API key using Authorization: Bearer <api_key>."}},"schemas":{"PublicApiInfoResponseDto":{"type":"object","properties":{"name":{"type":"string","example":"Trendtrack Public API","description":"Public API product name."},"version":{"type":"string","example":"v1","description":"Current public API version."},"status":{"type":"string","example":"ok","description":"Bootstrap health indicator."}},"required":["name","version","status"]},"PublicApiErrorDetailsDto":{"type":"object","properties":{"code":{"type":"string","example":"missing_api_key","description":"Stable public error code."},"message":{"type":"string","example":"Provide an API key using Authorization: Bearer <api_key>.","description":"Human-readable error message."},"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"details":{"type":"object","additionalProperties":true,"description":"Optional structured details, such as validation errors or credit availability metadata.","example":{"validationErrors":[{"field":"query-string.limit","location":"query-string","expected":["limit must not be greater than 100"]}]}}},"required":["code","message","requestId"]},"PublicApiErrorResponseDto":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/PublicApiErrorDetailsDto"}},"required":["error"]},"PublicApiHealthResponseDto":{"type":"object","properties":{"status":{"type":"string","example":"ok","description":"Health status for the public bootstrap."},"timestamp":{"type":"string","example":"2026-04-20T07:28:18.700Z","format":"date-time","description":"ISO timestamp captured when the health check was served."},"uptime":{"type":"number","example":123,"description":"Process uptime in seconds."}},"required":["status","timestamp","uptime"]},"PublicApiSystemFreshnessDataDto":{"type":"object","properties":{"latestReadyDate":{"type":"string","nullable":true,"example":"2026-04-23","description":"Latest global snapshot date with usable reach rows, or null when none exists."},"latestScheduledDate":{"type":"string","nullable":true,"example":"2026-04-24","description":"Latest global indexed/scheduled snapshot date observed in reach history, even if not ready yet."},"dataFreshnessLagDays":{"type":"number","nullable":true,"example":1,"description":"Difference in whole UTC days between today and latestReadyDate. Null when no ready snapshot exists."},"generatedAt":{"type":"string","example":"2026-04-24T14:42:14.123Z","format":"date-time","description":"ISO timestamp captured when this freshness payload was generated."}},"required":["latestReadyDate","latestScheduledDate","dataFreshnessLagDays","generatedAt"]},"PublicApiSystemFreshnessResponseDto":{"type":"object","properties":{"status":{"type":"string","example":"ok","description":"System freshness endpoint status."},"data":{"$ref":"#/components/schemas/PublicApiSystemFreshnessDataDto"}},"required":["status","data"]},"PublicApiCredentialDto":{"type":"object","properties":{"id":{"type":"string","example":"cred_123"},"name":{"type":"string","example":"Production key"},"description":{"type":"string","example":null,"nullable":true,"description":"Optional credential description."},"accessLevel":{"type":"string","enum":["full_access","delegated_user"],"example":"full_access"},"expiresAt":{"type":"string","example":null,"nullable":true,"format":"date-time","description":"Credential expiration timestamp when configured."},"createdAt":{"type":"string","example":"2026-04-20T07:24:00.246Z","format":"date-time"},"lastUsedAt":{"type":"string","example":"2026-04-20T07:28:18.681Z","format":"date-time"}},"required":["id","name","description","accessLevel","expiresAt","createdAt","lastUsedAt"]},"PublicApiWorkspaceDto":{"type":"object","properties":{"id":{"type":"string","example":"ws_123"},"slug":{"type":"string","example":"my-workspace"},"name":{"type":"string","example":"My Workspace"},"createdAt":{"type":"string","example":"2024-11-12T16:12:43.931Z","format":"date-time"}},"required":["id","slug","name","createdAt"]},"PublicApiDelegatedUserDto":{"type":"object","properties":{"id":{"type":"string","example":"usr_123"},"fullName":{"type":"string","example":"Jane Doe","nullable":true},"avatarUrl":{"type":"string","example":"https://cdn.example.com/avatar.png","nullable":true},"workspaceRole":{"type":"string","enum":["owner","admin","member","readonly"],"example":"admin"}},"required":["id","fullName","avatarUrl","workspaceRole"]},"PublicApiMeResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"credential":{"$ref":"#/components/schemas/PublicApiCredentialDto"},"workspace":{"$ref":"#/components/schemas/PublicApiWorkspaceDto"},"delegatedUser":{"nullable":true,"description":"Delegated user context when the credential access level is delegated_user.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiDelegatedUserDto"}]}},"required":["requestId","credential","workspace","delegatedUser"]},"PublicApiUsageWorkspaceDto":{"type":"object","properties":{"id":{"type":"string","example":"ws_123"},"slug":{"type":"string","example":"my-workspace"},"name":{"type":"string","example":"My Workspace"}},"required":["id","slug","name"]},"PublicApiUsageCredentialDto":{"type":"object","properties":{"id":{"type":"string","example":"cred_123"},"accessLevel":{"type":"string","enum":["full_access","delegated_user"],"example":"full_access"},"lastUsedAt":{"type":"string","example":"2026-04-20T07:28:18.700Z","format":"date-time"}},"required":["id","accessLevel","lastUsedAt"]},"PublicApiUsageBillingDto":{"type":"object","properties":{"configured":{"type":"boolean","example":false,"description":"Whether the workspace currently has billing configuration for the public API."},"planCode":{"type":"string","example":null,"nullable":true,"description":"Current billing plan code when configured."},"currentPeriodStart":{"type":"string","example":null,"nullable":true,"format":"date-time"},"currentPeriodEnd":{"type":"string","example":null,"nullable":true,"format":"date-time"},"updatedAt":{"type":"string","example":null,"nullable":true,"format":"date-time"}},"required":["configured","planCode","currentPeriodStart","currentPeriodEnd","updatedAt"]},"PublicApiUsageIncludedQuotaDto":{"type":"object","properties":{"limit":{"type":"number","example":0},"used":{"type":"number","example":0},"remaining":{"type":"number","example":0}},"required":["limit","used","remaining"]},"PublicApiUsageTopupDto":{"type":"object","properties":{"balance":{"type":"number","example":0}},"required":["balance"]},"PublicApiUsageCreditsDto":{"type":"object","properties":{"balance":{"type":"number","example":0,"deprecated":true,"description":"Deprecated compatibility alias of credits.topup.balance."},"recurring":{"$ref":"#/components/schemas/PublicApiUsageIncludedQuotaDto"},"topup":{"$ref":"#/components/schemas/PublicApiUsageTopupDto"},"totalRemaining":{"type":"number","example":0,"description":"Total remaining recurring + top-up credits."}},"required":["balance","recurring","topup","totalRemaining"]},"PublicApiUsageResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"d96c0824-7083-4cb6-a968-ecc694117367","description":"Request identifier mirrored in the X-Request-Id response header."},"workspace":{"$ref":"#/components/schemas/PublicApiUsageWorkspaceDto"},"credential":{"$ref":"#/components/schemas/PublicApiUsageCredentialDto"},"billing":{"$ref":"#/components/schemas/PublicApiUsageBillingDto"},"includedQuota":{"deprecated":true,"description":"Deprecated compatibility block. Use credits.recurring and credits.totalRemaining instead.","allOf":[{"$ref":"#/components/schemas/PublicApiUsageIncludedQuotaDto"}]},"credits":{"$ref":"#/components/schemas/PublicApiUsageCreditsDto"}},"required":["requestId","workspace","credential","billing","includedQuota","credits"]},"PublicApiWorkspaceFolderDto":{"type":"object","properties":{"id":{"type":"number","example":12},"name":{"type":"string","example":"Competitors"},"rank":{"type":"number","example":1,"nullable":true},"brandtrackerCount":{"type":"number","example":8,"description":"Number of active brandtrackers currently assigned to this folder."}},"required":["id","name","rank","brandtrackerCount"]},"PublicApiGetWorkspaceFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceFolderDto"}}},"required":["requestId","data"]},"PublicApiWorkspaceAuthenticatedAsDto":{"type":"object","properties":{"accessLevel":{"type":"string","enum":["full_access","delegated_user"],"example":"full_access"},"delegatedUserId":{"type":"string","example":null,"nullable":true,"description":"Delegated user identifier when authenticated with a delegated credential."},"delegatedUserRole":{"type":"string","enum":["owner","admin","member","readonly"],"example":null,"nullable":true,"description":"Workspace role of the delegated user when present."}},"required":["accessLevel","delegatedUserId","delegatedUserRole"]},"PublicApiWorkspaceCredentialDto":{"type":"object","properties":{"id":{"type":"string","example":"cred_123"},"name":{"type":"string","example":"Production key"},"description":{"type":"string","example":null,"nullable":true},"expiresAt":{"type":"string","example":null,"nullable":true,"format":"date-time"},"createdAt":{"type":"string","example":"2026-04-20T07:24:00.246Z","format":"date-time"},"lastUsedAt":{"type":"string","example":"2026-04-20T07:28:18.682Z","format":"date-time"}},"required":["id","name","description","expiresAt","createdAt","lastUsedAt"]},"PublicApiWorkspaceResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"38558568-a304-4682-a798-2578e37345f0","description":"Request identifier mirrored in the X-Request-Id response header."},"workspace":{"$ref":"#/components/schemas/PublicApiWorkspaceDto"},"authenticatedAs":{"$ref":"#/components/schemas/PublicApiWorkspaceAuthenticatedAsDto"},"credential":{"$ref":"#/components/schemas/PublicApiWorkspaceCredentialDto"}},"required":["requestId","workspace","authenticatedAs","credential"]},"PublicApiFacetPaginationDto":{"type":"object","properties":{"limit":{"type":"number","example":100},"offset":{"type":"number","example":0},"total":{"type":"number","example":325}},"required":["limit","offset","total"]},"PublicApiFacetFilterUsageDto":{"type":"object","properties":{"resource":{"type":"string","enum":["shops","ads","emails","advertisers"],"example":"shops"},"fields":{"example":["categoryIds"],"type":"array","items":{"type":"string"}},"valueField":{"type":"string","enum":["id","slug"],"example":"id"}},"required":["resource","fields","valueField"]},"PublicApiFacetMetaDto":{"type":"object","properties":{"valueType":{"type":"string","enum":["number","uuid","slug"],"example":"number"},"filterUsage":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFacetFilterUsageDto"}}},"required":["valueType","filterUsage"]},"PublicApiCategoryFacetDto":{"type":"object","properties":{"id":{"type":"number","example":287},"name":{"type":"string","example":"Beauty"},"path":{"type":"string","nullable":true,"example":"Health & Beauty > Beauty"},"parentId":{"type":"number","nullable":true,"example":42},"usageCount":{"type":"number","example":1842}},"required":["id","name","path","parentId","usageCount"]},"PublicApiCategoryFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header."},"pagination":{"$ref":"#/components/schemas/PublicApiFacetPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacetMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiCategoryFacetDto"}}},"required":["requestId","pagination","meta","data"]},"PublicApiShopifyAppFacetDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"41c143a7-0000-4000-8000-000000000000"},"label":{"type":"string","example":"Klaviyo"},"iconUrl":{"type":"string","nullable":true,"example":"https://cdn.shopify.com/app-store/listing_images/example/icon.png"},"shopifyUrl":{"type":"string","nullable":true,"example":"https://apps.shopify.com/klaviyo-email-marketing"},"usageCount":{"type":"number","example":9281}},"required":["id","label","iconUrl","shopifyUrl","usageCount"]},"PublicApiShopifyAppFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header."},"pagination":{"$ref":"#/components/schemas/PublicApiFacetPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacetMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiShopifyAppFacetDto"}}},"required":["requestId","pagination","meta","data"]},"PublicApiTechnologyFacetDto":{"type":"object","properties":{"slug":{"type":"string","example":"shopify"},"id":{"type":"string","format":"uuid","example":"04504d0b-df46-4f62-98b6-d4d9e14a2282"},"name":{"type":"string","example":"Shopify"},"iconUrl":{"type":"string","nullable":true,"example":"shopify.svg"},"categories":{"example":["Ecommerce"],"type":"array","items":{"type":"string"}},"usageCount":{"type":"number","nullable":true,"example":12042}},"required":["slug","id","name","iconUrl","categories","usageCount"]},"PublicApiTechnologyFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header."},"pagination":{"$ref":"#/components/schemas/PublicApiFacetPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacetMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiTechnologyFacetDto"}}},"required":["requestId","pagination","meta","data"]},"PublicApiPixelFacetDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ffe94cf7-e81d-5c43-9253-359117b1a544"},"slug":{"type":"string","nullable":true,"example":null},"name":{"type":"string","example":"Meta Pixel"},"iconUrl":{"type":"string","nullable":true,"example":"meta.svg"},"categories":{"example":[],"type":"array","items":{"type":"string"}},"usageCount":{"type":"number","nullable":true,"example":null}},"required":["id","slug","name","iconUrl","categories","usageCount"]},"PublicApiPixelFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header."},"pagination":{"$ref":"#/components/schemas/PublicApiFacetPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacetMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiPixelFacetDto"}}},"required":["requestId","pagination","meta","data"]},"PublicApiThemeFacetDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8d5ff70-08eb-4e4f-95d2-d3992abf8907"},"name":{"type":"string","example":"SHRINE"},"usageCount":{"type":"number","example":1842}},"required":["id","name","usageCount"]},"PublicApiThemeFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header."},"pagination":{"$ref":"#/components/schemas/PublicApiFacetPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacetMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiThemeFacetDto"}}},"required":["requestId","pagination","meta","data"]},"PublicApiLookupBrandtrackerDto":{"type":"object","properties":{"id":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"name":{"type":"string","example":"Example Brand"},"facebookPageId":{"type":"string","example":"61554990830184"}},"required":["id","name","facebookPageId"]},"PublicApiLookupAdvertiserDto":{"type":"object","properties":{"id":{"type":"string","example":"61554990830184"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"facebookPageId":{"type":"string","example":"61554990830184"}},"required":["id","name","facebookPageId"]},"PublicApiLookupShopDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"examplebrand.com"},"name":{"type":"string","nullable":true,"example":"Example Brand"}},"required":["id","domain","name"]},"PublicApiLookupSignalsDto":{"type":"object","properties":{"activeAds":{"type":"number","nullable":true,"example":42,"description":"Active ads signal when available from lookup candidate ranking metadata."},"liveAdsCount":{"type":"number","nullable":true,"example":42,"description":"Live ads signal alias when available (same source as activeAds when only one is present)."},"reach30d":{"type":"number","nullable":true,"example":152340,"description":"30-day reach signal when available from lookup ranking metadata."},"totalReach":{"type":"number","nullable":true,"example":842100,"description":"Total/current reach signal when available from lookup ranking metadata."},"monthlyVisits":{"type":"number","nullable":true,"example":1200000,"description":"Monthly visits signal when available from lookup candidate ranking metadata."},"workspaceAddedAt":{"type":"string","nullable":true,"example":"2026-04-20T12:34:56.000Z","description":"Workspace-added timestamp signal when available from lookup candidate ranking metadata."},"hasBrandtracker":{"type":"boolean","example":true},"hasAdvertiser":{"type":"boolean","example":true},"hasShop":{"type":"boolean","example":true}},"required":["activeAds","liveAdsCount","reach30d","totalReach","monthlyVisits","workspaceAddedAt","hasBrandtracker","hasAdvertiser","hasShop"]},"PublicApiLookupResultDto":{"type":"object","properties":{"type":{"type":"string","enum":["brandtracker","advertiser","shop"],"example":"shop"},"matchType":{"type":"string","enum":["exact","fuzzy"],"example":"exact"},"matchField":{"type":"string","enum":["name","domain","facebookPageId","instagramHandle"],"example":"domain"},"score":{"type":"number","example":1,"description":"Lookup confidence score. Exact identifier/domain/name matches return 1; fuzzy candidates return lower scores."},"brandtracker":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiLookupBrandtrackerDto"}]},"advertiser":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiLookupAdvertiserDto"}]},"shop":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiLookupShopDto"}]},"signals":{"description":"Additive disambiguation signals derived from existing lookup candidate ranking/resource metadata.","allOf":[{"$ref":"#/components/schemas/PublicApiLookupSignalsDto"}]}},"required":["type","matchType","matchField","score","brandtracker","advertiser","shop","signals"]},"PublicApiLookupMetaDto":{"type":"object","properties":{"q":{"type":"string","example":"examplebrand.com"},"type":{"type":"string","enum":["auto","brandtracker","advertiser","shop"],"example":"auto"},"limit":{"type":"number","example":10},"returned":{"type":"number","example":3},"partial":{"type":"boolean","example":true,"description":"Present when type=auto returned successful resource matches while one or more lookup branches timed out."},"warnings":{"example":[{"code":"upstream_timeout","type":"advertiser","message":"advertiser lookup timed out. Returned available matches from other resource types."}],"type":"array","items":{"type":"array"}}},"required":["q","type","limit","returned"]},"PublicApiLookupResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiLookupResultDto"}},"meta":{"$ref":"#/components/schemas/PublicApiLookupMetaDto"}},"required":["requestId","data","meta"]},"PublicApiFacebookShopResolveInputDto":{"type":"object","properties":{"type":{"type":"string","enum":["facebookPage","shop"],"example":"facebookPage"},"id":{"type":"string","example":"61554990830184"}},"required":["type","id"]},"PublicApiFacebookShopResolveShopDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"examplebrand.com"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"rank":{"type":"string","nullable":true,"example":"Main"},"isMainRelation":{"type":"boolean","example":true},"isPrimary":{"type":"boolean","example":true},"trafficNumber":{"type":"number","nullable":true,"example":125000},"profilePhotoUrl":{"type":"string","nullable":true,"example":"https://cdn.example.com/shop.png"}},"required":["id","domain","name","rank","isMainRelation","isPrimary","trafficNumber","profilePhotoUrl"]},"PublicApiFacebookShopResolveFacebookPageDto":{"type":"object","properties":{"id":{"type":"string","example":"61554990830184"},"facebookPageId":{"type":"string","example":"61554990830184"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"rank":{"type":"string","nullable":true,"example":"Main"},"isMainRelation":{"type":"boolean","example":true},"isPrimary":{"type":"boolean","example":true},"runningAds":{"type":"number","nullable":true,"example":42}},"required":["id","facebookPageId","name","rank","isMainRelation","isPrimary","runningAds"]},"PublicApiFacebookShopResolveDataDto":{"type":"object","properties":{"input":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveInputDto"},"primaryShop":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiFacebookShopResolveShopDto"}]},"shops":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveShopDto"}},"primaryFacebookPage":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiFacebookShopResolveFacebookPageDto"}]},"facebookPages":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveFacebookPageDto"}}},"required":["input","primaryShop","shops","primaryFacebookPage","facebookPages"]},"PublicApiFacebookShopResolveMetaDto":{"type":"object","properties":{"limit":{"type":"number","example":50},"returnedShops":{"type":"number","example":2},"returnedFacebookPages":{"type":"number","example":0}},"required":["limit","returnedShops","returnedFacebookPages"]},"PublicApiFacebookShopResolveResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveDataDto"},"meta":{"$ref":"#/components/schemas/PublicApiFacebookShopResolveMetaDto"}},"required":["requestId","data","meta"]},"PublicApiAdvertisersListSearchType":{"type":"string","enum":["brand","domain"]},"PublicApiAdvertisersKeywordMode":{"type":"string","enum":["any","all"]},"PublicApiAdvertisersSortBy":{"type":"string","enum":["relevance","newest","activeAds","newAds","euAdsShare","reach","reach14d","followers"]},"PublicApiAdvertisersSortOrder":{"type":"string","enum":["asc","desc"]},"PublicApiAdvertisersActiveAdsPeriod":{"type":"string","enum":["current","last24h","last7d","last14d","last30d"]},"PublicApiAdvertisersAdsLaunchedPeriod":{"type":"string","enum":["last24h","last7d","last14d","last30d","last90d"]},"PublicApiAdvertisersReachPeriod":{"type":"string","enum":["last24h","last7d","last14d","last30d","last90d","total"]},"PublicApiAdvertisersPageType":{"type":"string","enum":["influencer","brand"]},"PublicApiAdvertisersShopifyLinked":{"type":"string","enum":["yes","no","all"]},"PublicApiAdvertisersGender":{"type":"string","enum":["male","female","all"]},"PublicApiAdvertiserProfileDto":{"type":"object","properties":{"likes":{"type":"number","nullable":true,"example":125000},"instagramFollowers":{"type":"number","nullable":true,"example":89000},"createdAt":{"type":"string","nullable":true,"format":"date-time","description":"Facebook/page-explorer page creation date, aligned with minFbPageCreationDate and maxFbPageCreationDate filters. This is not the internal database ingestion timestamp.","example":"2019-01-04T00:00:00.000Z"}},"required":["likes","instagramFollowers","createdAt"]},"PublicApiAdvertiserSummaryAdvertisingDto":{"type":"object","properties":{"activeAds":{"type":"number","nullable":true,"example":12,"description":"Active ads count, preferring page-explorer running_ads_count with relational fallback when unavailable."},"reach30d":{"type":"number","nullable":true,"example":452000,"description":"Advertiser reach over the last 30 days, preferring page-explorer eu_reach_30d with fb_page fallback when unavailable. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."}},"required":["activeAds","reach30d"]},"PublicApiAdvertiserLastAdPreviewDto":{"type":"object","properties":{"id":{"type":"string","example":"facebook:123456789"},"mediaUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/facebook/media/ad-1.mp4"},"thumbnailUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"}},"required":["id","mediaUrl","thumbnailUrl"]},"PublicApiAdvertiserMainLandingPagePreviewDto":{"type":"object","properties":{"landingPage":{"type":"string","example":"https://example.com/products/summer"},"screenshotUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/landing-pages/summer.jpg"}},"required":["landingPage","screenshotUrl"]},"PublicApiAdvertiserSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"61554990830184","description":"Current public advertiser identifier. This MVP uses the Facebook page id directly."},"platform":{"type":"string","enum":["facebook"],"example":"facebook"},"facebookPageId":{"type":"string","example":"61554990830184"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"logoUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/profile_picture/61554990830184.jpg"},"profile":{"$ref":"#/components/schemas/PublicApiAdvertiserProfileDto"},"advertising":{"$ref":"#/components/schemas/PublicApiAdvertiserSummaryAdvertisingDto"},"lastAds":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertiserLastAdPreviewDto"}},"mainLandingPages":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertiserMainLandingPagePreviewDto"}}},"required":["id","platform","facebookPageId","name","logoUrl","profile","advertising","lastAds","mainLandingPages"]},"PublicApiAdvertisersPaginationDto":{"type":"object","properties":{"limit":{"type":"number","example":20},"offset":{"type":"number","example":0},"total":{"type":"number","example":128}},"required":["limit","offset","total"]},"PublicApiAdvertisersMetaDto":{"type":"object","properties":{"isTruncated":{"type":"boolean","example":false,"description":"True when an intermediary aggregation-based search stage truncated the intermediate id set before the final advertiser query."}},"required":["isTruncated"]},"PublicApiGetAdvertisersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertiserSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdvertisersPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiAdvertisersMetaDto"}},"required":["requestId","data","pagination","meta"]},"PublicApiAdvertisersSearchType":{"type":"string","enum":["brand","domain","adCopy","websiteCopy","urlContains"],"description":"Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search."},"PublicApiAdvertisersCountryFilterDto":{"type":"object","properties":{"include":{"example":["FR","DE"],"description":"ISO 3166-1 alpha-2 country codes to include.","type":"array","items":{"type":"string"}},"exclude":{"example":["US"],"description":"ISO 3166-1 alpha-2 country codes to exclude.","type":"array","items":{"type":"string"}}}},"PublicApiAdvertisersCountryFilterMode":{"type":"string","enum":["reach","adCount"],"description":"Enum value accepted by this request. Allowed values: `reach`, `adCount`."},"PublicApiAdvertisersThresholdOperator":{"type":"string","enum":["gte","lte"],"description":"Threshold operator. Use `gte` for minimum growth and `lte` for maximum growth."},"PublicApiAdvertisersAdsGrowthPeriod":{"type":"string","enum":["last24h","last3d","last7d","last14d","last30d","last60d","last90d"],"description":"Indexed ads growth window."},"PublicApiAdvertisersAdsGrowthRuleDto":{"type":"object","properties":{"operator":{"example":"gte","description":"Threshold operator. Use `gte` for minimum growth and `lte` for maximum growth.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersThresholdOperator"}]},"value":{"type":"number","example":20,"minimum":0,"description":"Growth threshold, expressed as a percentage."},"period":{"example":"last7d","description":"Indexed ads growth window.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersAdsGrowthPeriod"}]}},"required":["operator","value","period"]},"PublicApiAdvertisersAdsGrowthGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertisersAdsGrowthRuleDto"}}},"required":["all"]},"PublicApiAdvertisersAdsGrowthFilterDto":{"type":"object","properties":{"anyOf":{"description":"OR groups of ads growth rules. Each group combines its rules with AND.","example":[{"all":[{"period":"last7d","operator":"gte","value":40}]}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertisersAdsGrowthGroupDto"}}},"required":["anyOf"]},"PublicApiAdvertisersPageReachGrowthPeriod":{"type":"string","enum":["last7d","last14d","last30d","last60d","last90d"],"description":"Indexed page reach growth window."},"PublicApiAdvertisersPageReachGrowthRuleDto":{"type":"object","properties":{"operator":{"example":"gte","description":"Threshold operator. Use `gte` for minimum growth and `lte` for maximum growth.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersThresholdOperator"}]},"value":{"type":"number","example":20,"minimum":0,"description":"Growth threshold, expressed as a percentage."},"period":{"example":"last7d","description":"Indexed page reach growth window.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersPageReachGrowthPeriod"}]}},"required":["operator","value","period"]},"PublicApiAdvertisersPageReachGrowthGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertisersPageReachGrowthRuleDto"}}},"required":["all"]},"PublicApiAdvertisersPageReachGrowthFilterDto":{"type":"object","properties":{"anyOf":{"description":"OR groups of page reach growth rules. Each group combines its rules with AND.","example":[{"all":[{"period":"last7d","operator":"gte","value":50}]}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertisersPageReachGrowthGroupDto"}}},"required":["anyOf"]},"PublicApiAdvertisersPageNichesFilterDto":{"type":"object","properties":{"main":{"example":[254],"description":"Advanced legacy page-niche categories that must match the main advertiser page niche.","type":"array","items":{"type":"number"}},"among":{"example":[268],"description":"Advanced legacy page-niche categories that may appear among advertiser page niches.","type":"array","items":{"type":"number"}},"exclude":{"example":[987],"description":"Advanced legacy page-niche categories to exclude from advertiser page niches.","type":"array","items":{"type":"number"}}}},"QueryPublicApiAdvertisersRequestDto":{"type":"object","properties":{"search":{"example":["acme"],"type":"array","items":{"type":"string"}},"searchType":{"example":"adCopy","description":"Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersSearchType"}]},"keywordMode":{"example":"any","description":"Enum value accepted by this request. Allowed values: `any`, `all`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersKeywordMode"}]},"sortBy":{"example":"relevance","description":"Sort key for this request. Allowed values: `relevance`, `newest`, `activeAds`, `newAds`, `euAdsShare`, `reach`, `reach14d`, `followers`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersSortBy"}]},"order":{"example":"desc","description":"Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersSortOrder"}]},"offset":{"type":"number","example":0,"minimum":0},"limit":{"type":"number","example":20,"minimum":1,"maximum":100},"minFbPageCreationDate":{"type":"string","example":"2024-01-01"},"maxFbPageCreationDate":{"type":"string","example":"2024-12-31"},"minActiveAds":{"type":"number","minimum":0},"maxActiveAds":{"type":"number","minimum":0},"adsTimePeriod":{"example":"current","description":"Enum value accepted by this request. Allowed values: `current`, `last24h`, `last7d`, `last14d`, `last30d`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersActiveAdsPeriod"}]},"minFacebookLikes":{"type":"number","minimum":0},"maxFacebookLikes":{"type":"number","minimum":0},"minInstagramFollowers":{"type":"number","minimum":0},"maxInstagramFollowers":{"type":"number","minimum":0},"minAdsLaunched":{"type":"number","minimum":0},"maxAdsLaunched":{"type":"number","minimum":0},"adsLaunchedPeriod":{"example":"last30d","description":"Time window accepted by this request. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersAdsLaunchedPeriod"}]},"minReach":{"type":"number","minimum":0,"description":"Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"maxReach":{"type":"number","minimum":0,"description":"Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"reachPeriod":{"example":"last30d","description":"Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`, `total`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersReachPeriod"}]},"minSpendPerPage":{"type":"number","minimum":0,"description":"Minimum estimated spend per page. Converted internally through CPM and reach/impressions fields."},"maxSpendPerPage":{"type":"number","minimum":0,"description":"Maximum estimated spend per page. Converted internally through CPM and reach/impressions fields."},"spendPerPagePeriod":{"example":"last30d","description":"Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`, `total`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersReachPeriod"}]},"cpm":{"type":"number","minimum":0,"description":"CPM used to convert spend filters into reach/impressions-based ES ranges."},"minReachPerPage":{"type":"number","minimum":0,"description":"Minimum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data."},"maxReachPerPage":{"type":"number","minimum":0,"description":"Maximum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data."},"reachPerPagePeriod":{"example":"total","description":"Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: `last24h`, `last7d`, `last14d`, `last30d`, `last90d`, `total`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersReachPeriod"}]},"adLanguage":{"example":["en","fr"],"type":"array","items":{"type":"string"}},"technologies":{"example":["shopify","woocommerce"],"type":"array","items":{"type":"string"}},"adCountries":{"description":"Countries where the advertiser is distributing ads. Uses ISO 3166-1 alpha-2 country codes.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersCountryFilterDto"}]},"mainCountries":{"example":["FR","US"],"description":"Primary countries to match.","type":"array","items":{"type":"string"}},"countryFilterMode":{"example":"adCount","description":"Enum value accepted by this request. Allowed values: `reach`, `adCount`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersCountryFilterMode"}]},"adsGrowth":{"description":"Ads growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`), with rule fields `period`, `operator`, and `value`.","example":{"anyOf":[{"all":[{"period":"last7d","operator":"gte","value":40}]}]},"allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersAdsGrowthFilterDto"}]},"pageReachGrowth":{"description":"Page reach growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`), with rule fields `period`, `operator`, and `value`.","example":{"anyOf":[{"all":[{"period":"last7d","operator":"gte","value":50}]}]},"allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersPageReachGrowthFilterDto"}]},"ageRanges":{"example":["18-24","25-34"],"type":"array","items":{"type":"string"}},"pageType":{"type":"array","example":["brand"],"description":"Enum value accepted by this request. Allowed values: `influencer`, `brand`.","items":{"$ref":"#/components/schemas/PublicApiAdvertisersPageType"}},"categoryIds":{"example":[254],"description":"Google category facet ids matched through linked websites' website_overview.google_categories.","type":"array","items":{"type":"number"}},"pageNiches":{"description":"Not supported: advertiser page niches are not indexed, so any non-empty selection is rejected with 400 unsupported_filter. Use categoryIds, which matches linked websites via google_categories.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersPageNichesFilterDto"}]},"minPartnershipPercentage":{"type":"number","minimum":0,"maximum":100},"shopifyLinked":{"example":"yes","description":"Filter by indexed linked-site Shopify technology. `no` means no indexed Shopify technology is present for the advertiser.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersShopifyLinked"}]},"gender":{"example":"female","description":"Enum value accepted by this request. Allowed values: `male`, `female`, `all`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdvertisersGender"}]}}},"PublicApiAdvertiserAdsStatus":{"type":"string","enum":["all","active","inactive"]},"PublicApiAdvertiserAdsMediaType":{"type":"string","enum":["all","image","video"]},"PublicApiAdvertiserAdsSortBy":{"type":"string","enum":["newest","createdAt","longestRunning","reach","duplicates"]},"PublicApiAdvertiserAdsSortOrder":{"type":"string","enum":["asc","desc"]},"PublicApiAdMediaDto":{"type":"object","properties":{"type":{"type":"string","enum":["image","video","carousel","unknown"],"example":"video","description":"Creative media type from indexed ad data. `carousel` means carousel creative format and is not a DCO signal."},"thumbnailUrl":{"type":"string","nullable":true,"example":"https://cdn.example.com/ads/ad-1-thumb.jpg"},"mediaUrl":{"type":"string","nullable":true,"example":"https://cdn.example.com/ads/ad-1.mp4"}},"required":["type","thumbnailUrl","mediaUrl"]},"PublicApiAdAdvertiserDto":{"type":"object","properties":{"id":{"type":"string","nullable":true,"example":"1234567890"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"logoUrl":{"type":"string","nullable":true,"example":"https://cdn.example.com/pages/example-brand.png"},"facebookPageId":{"type":"string","nullable":true,"example":"1234567890"},"liveAdsCount":{"type":"number","nullable":true,"example":42},"reach30d":{"type":"number","nullable":true,"example":152340,"description":"Advertiser reach for the last 30 days. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"totalReach":{"type":"number","nullable":true,"example":842100,"description":"Advertiser total/current reach. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"countriesCount":{"type":"number","nullable":true,"example":8},"facebookLikes":{"type":"number","nullable":true,"example":125000},"instagramFollowers":{"type":"number","nullable":true,"example":89000}},"required":["id","name","logoUrl","facebookPageId","liveAdsCount","reach30d","totalReach","countriesCount","facebookLikes","instagramFollowers"]},"PublicApiAdContentSummaryDto":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Summer Sale"},"body":{"type":"string","nullable":true,"example":"Up to 30% off selected products."},"transcript":{"type":"string","nullable":true,"description":"Backward-compatible plain transcript text. Rich transcript metadata may also be available on detail responses.","example":"Save 30% on every order."},"callToAction":{"type":"string","nullable":true,"example":"Shop now"},"landingPageUrl":{"type":"string","nullable":true,"example":"https://example.com/products/summer-sale"},"landingPageDomain":{"type":"string","nullable":true,"example":"example.com"},"ctaDescription":{"type":"string","nullable":true,"example":"Free shipping on orders over $50."},"ctaLinkDescription":{"type":"string","nullable":true,"example":"Shop the full collection"}},"required":["title","body","transcript","callToAction","landingPageUrl","landingPageDomain","ctaDescription","ctaLinkDescription"]},"PublicApiAdMetricsDto":{"type":"object","properties":{"reach":{"type":"number","nullable":true,"description":"Ad reach where available. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric.","example":152340},"aggregatedReach":{"type":"number","nullable":true,"description":"Aggregated ad reach across duplicates where available; reach corresponds to the public impressions-style metric from Meta Ad Library data.","example":284100},"estimatedSpend":{"type":"number","nullable":true,"description":"Estimated spend in euros. Formula: reach * cpm / 1000, using the request cpm or the default CPM of 9 when cpm is omitted. Rounded to the nearest integer.","example":4262},"duplicates":{"type":"number","nullable":true,"example":4},"reachDelta1d":{"type":"number","nullable":true,"description":"One-day reach delta; reach corresponds to the public impressions-style metric from Meta Ad Library data.","example":1200},"reachDelta7d":{"type":"number","nullable":true,"description":"Seven-day reach delta; reach corresponds to the public impressions-style metric from Meta Ad Library data.","example":8200},"reachDelta30d":{"type":"number","nullable":true,"description":"Thirty-day reach delta; reach corresponds to the public impressions-style metric from Meta Ad Library data.","example":38400}},"required":["reach","aggregatedReach","estimatedSpend","duplicates","reachDelta1d","reachDelta7d","reachDelta30d"]},"PublicApiAdAudienceDto":{"type":"object","properties":{"targetedCountries":{"nullable":true,"example":["US","FR"],"description":"Full ad targeting country list, including non-EU markets such as US.","type":"array","items":{"type":"string"}},"mainCountry":{"type":"string","nullable":true,"example":"FR","description":"Primary audience country from Meta's EU/UK ad transparency reporting. Null for ads outside that scope, even when targetedCountries is populated."},"gender":{"type":"string","enum":["men","women","all"],"nullable":true,"example":"all"},"ageMin":{"type":"number","nullable":true,"example":18},"ageMax":{"type":"number","nullable":true,"example":65}},"required":["targetedCountries","mainCountry","gender","ageMin","ageMax"]},"PublicApiAdRankDto":{"type":"object","properties":{"positionInPage":{"type":"number","nullable":true,"example":3},"currentRank":{"type":"number","nullable":true,"example":12},"rankDelta":{"type":"number","nullable":true,"example":-4},"improvementPct":{"type":"number","nullable":true,"example":0.25}},"required":["positionInPage","currentRank","rankDelta","improvementPct"]},"PublicApiAdFlagsDto":{"type":"object","properties":{"isEuAd":{"type":"boolean","nullable":true,"example":true},"isLowReach":{"type":"boolean","nullable":true,"example":false,"description":"Whether the ad is flagged as low reach/low impressions in the indexed Meta Ad Library data."},"isMediaChanged":{"type":"boolean","nullable":true,"example":false},"hasPartnerBadge":{"type":"boolean","nullable":true,"example":true}},"required":["isEuAd","isLowReach","isMediaChanged","hasPartnerBadge"]},"PublicApiAdSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"facebook_123456789"},"collationId":{"type":"string","description":"Creative collation identifier when this result represents a deduplicated group of related Meta ads. Pass this value as scan_ad.collation_id to scan the same combined creative shown by search.","example":"3810635369204881"},"platform":{"type":"string","enum":["facebook"],"example":"facebook"},"status":{"type":"string","enum":["active","inactive","unknown"],"description":"For a result with collationId, active means at least one media-backed member ad is active. Without collationId, this is the individual ad status.","example":"active"},"createdAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-18T12:30:00.000Z"},"firstSeenAt":{"type":"string","nullable":true,"format":"date-time","description":"For a result with collationId, the earliest first-seen date across the combined creative members.","example":"2026-04-10T00:00:00.000Z"},"lastSeenAt":{"type":"string","nullable":true,"format":"date-time","description":"For a result with collationId, null while any media-backed member remains active; otherwise the latest member end date.","example":"2026-04-19T00:00:00.000Z"},"daysRunning":{"type":"number","nullable":true,"description":"Indexed running duration in days. For a result with collationId, this is the creative calendar span from the oldest member start to today while any member is active, or to the latest member end otherwise; it does not imply continuous delivery by one ad. Historical backfill is bounded by the available firstSeenAt floor (currently 2018-01-01), so very old ads can share the same maximum/clamped value.","example":9},"media":{"$ref":"#/components/schemas/PublicApiAdMediaDto"},"advertiser":{"$ref":"#/components/schemas/PublicApiAdAdvertiserDto"},"content":{"$ref":"#/components/schemas/PublicApiAdContentSummaryDto"},"metrics":{"$ref":"#/components/schemas/PublicApiAdMetricsDto"},"audience":{"$ref":"#/components/schemas/PublicApiAdAudienceDto"},"rank":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiAdRankDto"}]},"flags":{"$ref":"#/components/schemas/PublicApiAdFlagsDto"}},"required":["id","platform","status","createdAt","firstSeenAt","lastSeenAt","daysRunning","media","advertiser","content","metrics","audience","rank","flags"]},"PublicApiAdvertiserAdsPaginationDto":{"type":"object","properties":{"limit":{"type":"number","example":25},"offset":{"type":"number","example":0},"total":{"type":"number","example":128}},"required":["limit","offset","total"]},"PublicApiGetAdvertiserAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdvertiserAdsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiAdvertiserLinkedShopDto":{"type":"object","properties":{"shopId":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","nullable":true,"example":"Example Shop"},"isPrimary":{"type":"boolean","example":true}},"required":["shopId","domain","name","isPrimary"]},"PublicApiAdvertiserCountryDistributionDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US"},"share":{"type":"number","nullable":true,"example":0.42,"description":"Share is returned only when a reach-based distribution can be derived cleanly from advertiser ad data."}},"required":["countryCode","share"]},"PublicApiAdvertiserAdvertisingDto":{"type":"object","properties":{"activeAds":{"type":"number","example":12,"nullable":true,"description":"Active ads count, preferring page-explorer running_ads_count with relational fallback when unavailable."},"reach30d":{"type":"number","example":452000,"nullable":true,"description":"Advertiser reach over the last 30 days, preferring page-explorer eu_reach_30d with fb_page.impressions_last_month fallback when unavailable. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"countryDistribution":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertiserCountryDistributionDto"}}},"required":["activeAds","reach30d","countryDistribution"]},"PublicApiAdvertiserDetailDto":{"type":"object","properties":{"id":{"type":"string","example":"61554990830184","description":"Current MVP uses the Facebook page id directly as the public advertiser id."},"platform":{"type":"string","enum":["facebook"],"example":"facebook"},"facebookPageId":{"type":"string","example":"61554990830184"},"name":{"type":"string","nullable":true,"example":"Example Brand"},"logoUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/profile_picture/61554990830184.jpg"},"profile":{"$ref":"#/components/schemas/PublicApiAdvertiserProfileDto"},"linkedShops":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdvertiserLinkedShopDto"}},"advertising":{"$ref":"#/components/schemas/PublicApiAdvertiserAdvertisingDto"},"lastAds":{"description":"Most recent advertiser ads using the shared public ad summary contract.","type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}}},"required":["id","platform","facebookPageId","name","logoUrl","profile","linkedShops","advertising","lastAds"]},"PublicApiGetAdvertiserDetailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiAdvertiserDetailDto"}},"required":["requestId","data"]},"PublicApiAdsListSearchType":{"type":"string","enum":["adCopy","brand"]},"PublicApiAdsPlatform":{"type":"string","enum":["facebook","all"]},"PublicApiAdsStatus":{"type":"string","enum":["active","inactive","all"]},"PublicApiAdsMediaType":{"type":"string","enum":["image","video","carousel"]},"PublicApiAdsListSort":{"type":"string","enum":["relevance","newest","longestRunning","reach"]},"PublicApiAdsPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25},"total":{"type":"number","nullable":true,"example":235},"totalPages":{"type":"number","nullable":true,"example":10}},"required":["page","limit","total","totalPages"]},"PublicApiSearchAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiAdsCountryFilterDto":{"type":"object","properties":{"include":{"example":["US","CA"],"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes to include."},"exclude":{"example":["BR","IN"],"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes to exclude."}}},"PublicApiAdsThresholdOperator":{"type":"string","enum":["gte","lte"],"description":"Comparison operator for this rule. Allowed values: `gte`, `lte`."},"PublicApiAdsReachGrowthPeriod":{"type":"string","enum":["last7d","last14d","last30d","last60d","last90d"],"description":"Time window accepted by this request. Allowed values: `last7d`, `last14d`, `last30d`, `last60d`, `last90d`."},"PublicApiAdsReachGrowthRuleDto":{"type":"object","properties":{"operator":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsThresholdOperator"}],"description":"Comparison operator for this rule. Allowed values: `gte`, `lte`.","example":"gte"},"value":{"type":"number","example":50,"minimum":0},"period":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsReachGrowthPeriod"}],"description":"Time window accepted by this request. Allowed values: `last7d`, `last14d`, `last30d`, `last60d`, `last90d`.","example":"last7d"}},"required":["operator","value","period"]},"PublicApiAdsReachGrowthGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsReachGrowthRuleDto"}}},"required":["all"]},"PublicApiAdsReachGrowthFilterDto":{"type":"object","properties":{"anyOf":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsReachGrowthGroupDto"},"description":"OR groups of reach growth rules. Each group combines its rules with AND.","example":{"anyOf":[{"all":[{"period":"last7d","operator":"gte","value":50}]}]}}},"required":["anyOf"]},"PublicApiAdsAdsGrowthPeriod":{"type":"string","enum":["last7d","last30d","last90d"],"description":"Time window accepted by this request. Allowed values: `last7d`, `last30d`, `last90d`."},"PublicApiAdsAdsGrowthRuleDto":{"type":"object","properties":{"operator":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsThresholdOperator"}],"description":"Comparison operator for this rule. Allowed values: `gte`, `lte`.","example":"gte"},"value":{"type":"number","example":50,"minimum":0},"period":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsAdsGrowthPeriod"}],"description":"Time window accepted by this request. Allowed values: `last7d`, `last30d`, `last90d`.","example":"last7d"}},"required":["operator","value","period"]},"PublicApiAdsAdsGrowthGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsAdsGrowthRuleDto"}}},"required":["all"]},"PublicApiAdsAdsGrowthFilterDto":{"type":"object","properties":{"anyOf":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsAdsGrowthGroupDto"},"description":"OR groups of ads growth rules. Each group combines its rules with AND.","example":{"anyOf":[{"all":[{"period":"last7d","operator":"gte","value":40}]}]}}},"required":["anyOf"]},"PublicApiAdsGrowthRankPeriod":{"type":"string","enum":["last3d","last7d","last14d","last30d"],"description":"Accepted for forward-compatible request shapes. Current filtering is backed by the 3-day rank direction field."},"PublicApiAdsGrowthRankDirection":{"type":"string","enum":["rising","falling","stable"],"description":"Enum value accepted by this request. Allowed values: `rising`, `falling`, `stable`."},"PublicApiAdsGrowthRankUnit":{"type":"string","enum":["percent","absolute"],"description":"Accepted for forward-compatible request shapes. Current filtering only applies direction."},"PublicApiAdsGrowthRankRuleDto":{"type":"object","properties":{"period":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsGrowthRankPeriod"}],"description":"Accepted for forward-compatible request shapes. Current filtering is backed by the 3-day rank direction field.","example":"last7d"},"direction":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsGrowthRankDirection"}],"description":"Enum value accepted by this request. Allowed values: `rising`, `falling`, `stable`.","example":"rising"},"minChange":{"type":"number","minimum":0,"description":"Accepted for forward-compatible request shapes. Current filtering only applies direction.","example":20},"unit":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsGrowthRankUnit"}],"description":"Accepted for forward-compatible request shapes. Current filtering only applies direction.","example":"percent"}},"required":["period","direction"]},"PublicApiAdsGrowthRankGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsGrowthRankRuleDto"}}},"required":["all"]},"PublicApiAdsGrowthRankFilterDto":{"type":"object","properties":{"anyOf":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsGrowthRankGroupDto"},"description":"Structured rank trend request shape. Current filtering ORs all provided directions and ignores grouping, period, minChange, and unit.","example":{"anyOf":[{"all":[{"period":"last7d","direction":"rising","minChange":20,"unit":"percent"}]}]}}},"required":["anyOf"]},"PublicApiAdsMarketFilterDto":{"type":"object","properties":{"main":{"example":["US"],"type":"array","items":{"type":"string"},"description":"Countries that must match the primary market."},"among":{"example":["CA","GB"],"type":"array","items":{"type":"string"},"description":"Countries that can appear among the ad markets."},"exclude":{"example":["AU"],"type":"array","items":{"type":"string"},"description":"Countries to exclude from the ad markets."}}},"PublicApiAdsTrafficGrowthPeriod":{"type":"string","enum":["last30d","last90d","last180d"],"description":"Time window accepted by this request. Allowed values: `last30d`, `last90d`, `last180d`."},"PublicApiAdsTrafficGrowthRuleDto":{"type":"object","properties":{"operator":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsThresholdOperator"}],"description":"Comparison operator for this rule. Allowed values: `gte`, `lte`.","example":"gte"},"value":{"type":"number","example":50,"minimum":0},"period":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsTrafficGrowthPeriod"}],"description":"Time window accepted by this request. Allowed values: `last30d`, `last90d`, `last180d`.","example":"last30d"}},"required":["operator","value","period"]},"PublicApiAdsTrafficGrowthGroupDto":{"type":"object","properties":{"all":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsTrafficGrowthRuleDto"}}},"required":["all"]},"PublicApiAdsTrafficGrowthFilterDto":{"type":"object","properties":{"anyOf":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsTrafficGrowthGroupDto"},"description":"OR groups of traffic growth rules. Each group combines its rules with AND.","example":{"anyOf":[{"all":[{"period":"last30d","operator":"gte","value":50}]}]}}},"required":["anyOf"]},"PublicApiAdsQuerySearchType":{"type":"string","enum":["adCopy","brand","website","domain","urlContains"],"description":"Search mode for this request. Public camelCase values map to the same internal /ads fields: `adCopy` → `ad_copy`, `brand` → `brand`, `website` → `website_copy`, `domain` → `domain`, `urlContains` → `url_contains`."},"PublicApiAdsKeywordMode":{"type":"string","enum":["any","all"],"description":"How multiple search keywords are combined. Allowed values: `any`, `all`."},"PublicApiAdsQuerySort":{"type":"string","enum":["createdAt","longestRunning","relevance","relevanceScore","newest","mostDuplicates","reach","reachDelta1d","reachDelta7d","reachDelta30d","rankDelta7d","rankDelta14d","rankDelta30d","adOrder"],"description":"Sort key for this request. Allowed values: `createdAt`, `longestRunning`, `relevance`, `relevanceScore`, `newest`, `mostDuplicates`, `reach`, `reachDelta1d`, `reachDelta7d`, `reachDelta30d`, `adOrder`."},"PublicApiAdsSortOrder":{"type":"string","enum":["asc","desc"],"description":"Sort direction for this request. Allowed values: `asc`, `desc`."},"PublicApiAdsQueryPlatform":{"type":"string","enum":["facebook"],"description":"Accepted public v1 platform values. TikTok is not available in public v1."},"PublicApiAdsRankMode":{"type":"string","enum":["percentile","rank"],"description":"Rank interpretation mode. Allowed values: `percentile`, `rank`."},"PublicApiAdsRankBasis":{"type":"string","enum":["current","alltime"],"description":"Rank basis used for ad rank filters. Allowed values: `current`, `alltime`."},"PublicApiAdsRankDeltaWindow":{"type":"string","enum":["7d","14d","30d"],"description":"Rank-delta window used by growthRank/minRankDelta. Overrides the window inferred from growthRank.period."},"PublicApiAdsSex":{"type":"string","enum":["men","women","all"],"description":"Audience gender filter. Allowed values: `men`, `women`, `all`."},"PublicApiAdsSpender":{"type":"string","enum":["big-spender","rising-star","brandtracker"],"description":"Spender segment filter. Allowed values: `big-spender`, `rising-star`, `brandtracker`."},"PublicApiAdsTimePeriod":{"type":"string","enum":["last24h","last7d","last30d"],"description":"Relative ad first-seen time window. When createdAfter is omitted, this is converted to an internal first-seen lower bound at the UTC day boundary for the selected period. It also selects the ads metric period used by minAds/maxAds."},"PublicApiAdsShopifyPlus":{"type":"string","enum":["plus","non-plus","all"],"description":"Shopify Plus filter. Allowed values: `plus`, `non-plus`, `all`."},"PublicApiAdsMetricPeriod":{"type":"string","enum":["total","last24h","last7d","last30d"],"description":"Metric period used by minSpend/maxSpend. By itself this parameter does not filter results."},"QueryPublicApiAdsRequestDto":{"type":"object","properties":{"search":{"example":["summer dress","linen"],"type":"array","items":{"type":"string"},"description":"Optional list of search terms used by the advanced ads query engine."},"searchType":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsQuerySearchType"}],"description":"Search mode for this request. Public camelCase values map to the same internal /ads fields: `adCopy` → `ad_copy`, `brand` → `brand`, `website` → `website_copy`, `domain` → `domain`, `urlContains` → `url_contains`.","example":"adCopy"},"keywordMode":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsKeywordMode"}],"description":"How multiple search keywords are combined. Allowed values: `any`, `all`.","example":"any"},"sortBy":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsQuerySort"}],"description":"Sort key for this request. Allowed values: `createdAt`, `longestRunning`, `relevance`, `relevanceScore`, `newest`, `mostDuplicates`, `reach`, `reachDelta1d`, `reachDelta7d`, `reachDelta30d`, `adOrder`.","example":"relevance"},"order":{"description":"Sort direction for this request. Allowed values: `asc`, `desc`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdsSortOrder"}],"example":"desc"},"page":{"type":"number","example":1,"minimum":1},"limit":{"type":"number","example":50,"minimum":1,"maximum":100},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsQueryPlatform"},"description":"Accepted public v1 platform values. TikTok is not available in public v1.","example":["facebook"]},"mediaType":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMediaType"}],"description":"Creative media type filter for this request. Allowed values: `image`, `video`, `carousel`. `carousel` maps to indexed carousel creatives and is not a DCO filter.","example":"video"},"createdAfter":{"type":"string","format":"date-time"},"createdBefore":{"type":"string","format":"date-time"},"minFbPageCreationDate":{"type":"string","format":"date-time"},"maxFbPageCreationDate":{"type":"string","format":"date-time"},"minLastSeenDate":{"type":"string","format":"date-time"},"maxLastSeenDate":{"type":"string","format":"date-time"},"minDaysRunning":{"type":"number","minimum":0},"maxDaysRunning":{"type":"number","minimum":0},"status":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsStatus"}],"description":"Status filter for this request. Allowed values: `active`, `inactive`, `all`.","example":"all"},"minDuplicates":{"type":"number","minimum":0},"maxDuplicates":{"type":"number","minimum":0},"minDescriptionLength":{"type":"number","minimum":0},"maxDescriptionLength":{"type":"number","minimum":0},"minVideoDuration":{"type":"number","minimum":0},"maxVideoDuration":{"type":"number","minimum":0},"maxAdOrder":{"type":"number","minimum":1},"adRankMode":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsRankMode"}],"description":"Rank interpretation mode. Allowed values: `percentile`, `rank`."},"adRankBasis":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsRankBasis"}],"description":"Rank basis used for ad rank filters. Allowed values: `current`, `alltime`."},"maxAdRankValue":{"type":"number","minimum":1},"growthRank":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsGrowthRankFilterDto"}],"description":"Advanced rank trend filter. Direction filters are ORed; period selects the rank-delta window when every rule uses the same supported window. minChange/unit are accepted for forward compatibility; use minRankDelta for an enforced absolute minimum rank improvement."},"rankDeltaWindow":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsRankDeltaWindow"}],"description":"Rank-delta window used by growthRank/minRankDelta. Overrides the window inferred from growthRank.period."},"minRankDelta":{"type":"number","minimum":1,"description":"Minimum absolute rank improvement for ad-rank mover filters."},"adLanguage":{"type":"array","items":{"type":"string"}},"cta":{"type":"array","items":{"type":"string"}},"landingPages":{"type":"array","items":{"type":"string"},"description":"Landing page URL/domain filters. Mirrors the app ads table landingPages filter."},"adCopyHashes":{"type":"array","items":{"type":"string"},"description":"Ad copy hash filters. Mirrors the app ads table adCopyHashes filter."},"minReach":{"type":"number","minimum":0,"description":"Minimum reach threshold. Backed by the internal reach/impressions analytics fields."},"maxReach":{"type":"number","minimum":0,"description":"Maximum reach threshold. Backed by the internal reach/impressions analytics fields."},"minAge":{"type":"number","minimum":0},"maxAge":{"type":"number","minimum":0},"sex":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsSex"}],"description":"Audience gender filter. Allowed values: `men`, `women`, `all`."},"adCountries":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsCountryFilterDto"}],"description":"Countries where the ad is distributed. Uses ISO 3166-1 alpha-2 country codes."},"mainCountries":{"type":"array","items":{"type":"string"},"description":"Primary audience country filter, backed by Meta's EU/UK ad transparency reporting. Only EU/EEA, UK and French overseas codes exist in that data: US and other non-EU codes match nothing. Use adCountries for those markets."},"spender":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsSpender"}],"description":"Spender segment filter. Allowed values: `big-spender`, `rising-star`, `brandtracker`."},"partners":{"type":"boolean"},"partnerIds":{"type":"array","items":{"type":"string"},"description":"Partner badge ids to include. Mirrors the app ads table partnerIds filter."},"minTraffic":{"type":"number","minimum":0},"maxTraffic":{"type":"number","minimum":0},"trafficGrowth":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsTrafficGrowthFilterDto"}],"description":"Traffic growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`). Values are percentage thresholds."},"minAds":{"type":"number","minimum":0},"maxAds":{"type":"number","minimum":0},"adsGrowth":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsAdsGrowthFilterDto"}],"description":"Ads growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`). Values are percentage thresholds."},"pageReachGrowth":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsReachGrowthFilterDto"}],"description":"Page reach growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`)."},"adReachGrowth":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsReachGrowthFilterDto"}],"description":"Ad reach growth filter. Uses OR groups (`anyOf`) made of AND-ed rules (`all`)."},"categoryIds":{"type":"array","items":{"type":"number"},"description":"Google category facet ids matched against ads/shop google_categories."},"minProducts":{"type":"number","minimum":0},"maxProducts":{"type":"number","minimum":0},"minBestSellerPrice":{"type":"number","minimum":0},"maxBestSellerPrice":{"type":"number","minimum":0},"themes":{"type":"array","items":{"type":"string"}},"pixels":{"type":"array","items":{"type":"string"}},"excludePixels":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"currencies":{"type":"array","items":{"type":"string"}},"shopifyApps":{"example":["41c143a7-0000-4000-8000-000000000000"],"description":"Shopify app UUIDs returned by the Shopify Apps facets endpoint.","type":"array","items":{"type":"string","format":"uuid"}},"excludeShopifyApps":{"example":["52d254b8-0000-4000-8000-000000000000"],"description":"Shopify app UUIDs to exclude. Values must not overlap shopifyApps.","type":"array","items":{"type":"string","format":"uuid"}},"adsTimePeriod":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsTimePeriod"}],"description":"Relative ad first-seen time window. When createdAfter is omitted, this is converted to an internal first-seen lower bound at the UTC day boundary for the selected period. It also selects the ads metric period used by minAds/maxAds."},"minDate":{"type":"string","format":"date-time"},"maxDate":{"type":"string","format":"date-time"},"creationCountry":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsCountryFilterDto"}],"description":"Advertiser creation country filter using ISO 3166-1 alpha-2 country codes."},"market":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMarketFilterDto"}],"description":"Market filter grouped by primary markets, secondary markets, and excluded markets."},"shopifyPlus":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsShopifyPlus"}],"description":"Shopify Plus filter. Allowed values: `plus`, `non-plus`, `all`."},"minTrustpilotScore":{"type":"number","minimum":0,"description":"Minimum Trustpilot score."},"maxTrustpilotScore":{"type":"number","minimum":0,"description":"Maximum Trustpilot score."},"minTrustpilotReviews":{"type":"number","minimum":0,"description":"Minimum Trustpilot review count."},"maxTrustpilotReviews":{"type":"number","minimum":0,"description":"Maximum Trustpilot review count."},"minSpend":{"type":"number","minimum":0,"description":"Minimum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9."},"maxSpend":{"type":"number","minimum":0,"description":"Maximum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9."},"cpm":{"type":"number","minimum":0,"default":9,"description":"CPM in euros per 1,000 reach used for spend filters and estimatedSpend. Defaults to 9 when omitted."},"spendPeriod":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMetricPeriod"}],"description":"Metric period used by minSpend/maxSpend. By itself this parameter does not filter results."},"reachPeriod":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMetricPeriod"}],"description":"Metric period used by minReach/maxReach. Reach is the public Meta Ad Library vocabulary for impressions where available. Allowed values: `total`, `last24h`, `last7d`, `last30d`."},"minSpendPerPage":{"type":"number","minimum":0,"description":"Minimum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9."},"maxSpendPerPage":{"type":"number","minimum":0,"description":"Maximum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9."},"spendPerPagePeriod":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMetricPeriod"}],"description":"Metric period used by minSpendPerPage/maxSpendPerPage. By itself this parameter does not filter results."},"minFacebookLikes":{"type":"number","minimum":0},"maxFacebookLikes":{"type":"number","minimum":0},"minInstagramFollowers":{"type":"number","minimum":0},"maxInstagramFollowers":{"type":"number","minimum":0},"minReachPerPage":{"type":"number","minimum":0,"description":"Minimum page reach threshold. Backed by the internal page impressions fields."},"maxReachPerPage":{"type":"number","minimum":0,"description":"Maximum page reach threshold. Backed by the internal page impressions fields."},"reachPerPagePeriod":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdsMetricPeriod"}],"description":"Metric period used by minReachPerPage/maxReachPerPage. Reach is the public Meta Ad Library vocabulary for page impressions where available. Allowed values: `total`, `last24h`, `last7d`, `last30d`."},"technologies":{"type":"array","example":["shopify"],"items":{"type":"string","enum":["checkoutchamp","clickfunnels","funnelish","gempages","magento","odoo","pagefly","prestashop","shopify","shoplazza","shopline","squarespace","wheelio","wix","woocommerce","wordpress","zipify-pages"]},"description":"Technology slugs supported by the current ads index. Supported values: checkoutchamp, clickfunnels, funnelish, gempages, magento, odoo, pagefly, prestashop, shopify, shoplazza, shopline, squarespace, wheelio, wix, woocommerce, wordpress, zipify-pages."},"hideLowReach":{"type":"boolean","description":"Exclude low reach ads. Backed by the internal low impressions flag."},"hideNonEuUkAds":{"type":"boolean"},"hideSavedAds":{"type":"boolean"},"hideDecliningRankAds":{"type":"boolean"},"trackedPages":{"type":"array","items":{"type":"string"}},"maxAdsPerBrand":{"type":"number","minimum":0,"maximum":15}}},"PublicApiAdLandingPageFacetDto":{"type":"object","properties":{"url":{"type":"string","example":"https://www.example.com/products/item","description":"Normalized landing-page URL in lowercase, without query parameters or trailing slashes."},"usageCount":{"type":"number","example":8,"description":"Number of matching ads using this landing-page URL."},"activeAdsCount":{"type":"number","example":3,"description":"Number of matching active ads using this landing-page URL."}},"required":["url","usageCount","activeAdsCount"]},"PublicApiAdLandingPagesMetaDto":{"type":"object","properties":{"scopeType":{"type":"string","enum":["trackedPages","domain"],"example":"trackedPages"},"scopeValueCount":{"type":"number","example":2},"status":{"example":"all","allOf":[{"$ref":"#/components/schemas/PublicApiAdsStatus"}]},"limit":{"type":"number","example":100,"minimum":1,"maximum":100},"isTruncated":{"type":"boolean","example":false,"description":"True when more normalized domains matched than the response limit or Elasticsearch omitted buckets."}},"required":["scopeType","scopeValueCount","status","limit","isTruncated"]},"PublicApiGetAdLandingPagesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdLandingPageFacetDto"}},"meta":{"$ref":"#/components/schemas/PublicApiAdLandingPagesMetaDto"}},"required":["requestId","data","meta"]},"PublicApiAdShareDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789","description":"Trendtrack ad identifier returned as `adId` by the Public API."},"id":{"type":"string","description":"Identifier of the share_ads row used by the webapp share page.","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"slug":{"type":"string","nullable":true,"description":"Human-readable share slug when available.","example":"example-brand-9a8b7c"},"shareUrl":{"type":"string","description":"Fully qualified Trendtrack webapp URL for this public share.","example":"https://app.trendtrack.io/share/ads/example-brand-9a8b7c"},"sharePath":{"type":"string","description":"Webapp-relative path for this public share.","example":"/share/ads/example-brand-9a8b7c"},"createdAt":{"type":"string","format":"date-time","example":"2026-04-18T12:30:00.000Z"}},"required":["adId","id","slug","shareUrl","sharePath","createdAt"]},"PublicApiCreateAdShareResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiAdShareDto"}},"required":["requestId","data"]},"PublicApiAdShareDeletionDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789"},"deleted":{"type":"boolean"}},"required":["adId","deleted"]},"PublicApiDeleteAdShareResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiAdShareDeletionDto"}},"required":["requestId","data"]},"PublicApiAdMediaUrlDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789","description":"Trendtrack ad identifier returned as `adId` by the Public API."},"mediaType":{"type":"string","enum":["image","video","carousel","unknown"],"example":"video"},"url":{"type":"string","description":"Best available media URL for this ad. This endpoint returns metadata only and does not proxy the binary asset.","example":"https://medias.trendtrack.io/ads/ad-1.mp4"},"urlType":{"type":"string","enum":["public_asset","external_direct"],"description":"public_asset is a stable Trendtrack/public URL. external_direct may expire or be subject to upstream access controls.","example":"public_asset"},"selectedSource":{"type":"string","enum":["media_url","thumbnail_url"],"description":"Source column selected for url.","example":"media_url"},"mediaUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/ads/ad-1.mp4"},"thumbnailUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/ads/ad-1-thumb.jpg"},"filename":{"type":"string","description":"Suggested filename derived from the ad id and selected URL.","example":"facebook_123456789.mp4"}},"required":["adId","mediaType","url","urlType","selectedSource","mediaUrl","thumbnailUrl","filename"]},"PublicApiGetAdMediaUrlResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiAdMediaUrlDto"}},"required":["requestId","data"]},"PublicApiAdTranscriptSegmentDto":{"type":"object","properties":{"start":{"type":"number","example":0.4},"end":{"type":"number","example":3.2},"text":{"type":"string","example":"Save 30% on every order."}},"required":["start","end","text"]},"PublicApiAdTranscriptDto":{"type":"object","properties":{"language":{"type":"string","nullable":true,"example":"en"},"languageConfidence":{"type":"number","nullable":true,"example":0.97},"segments":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdTranscriptSegmentDto"}},"fullText":{"type":"string","nullable":true,"example":"Save 30% on every order."}},"required":["language","languageConfidence","segments","fullText"]},"PublicApiAdCreativeHookDto":{"type":"object","properties":{"text":{"type":"string","nullable":true,"description":"Resolved opening hook text from existing transcript or ad copy data. Truncated to 160 characters for preview consistency. No OCR or transcript generation is performed for this field.","example":"Yes, it is pricey. Also, worth it."},"source":{"type":"string","enum":["ad_transcripts_hook","transcript_first_3_seconds","transcript_full_text","body_fallback","unavailable"],"example":"ad_transcripts_hook"},"sourceDescription":{"type":"string","example":"Existing completed ad transcript hook."},"isFallback":{"type":"boolean","description":"True when the hook is derived from fallback ad copy rather than transcript-derived data.","example":false}},"required":["text","source","sourceDescription","isFallback"]},"PublicApiAdCreativeAnalysisDto":{"type":"object","properties":{"hook":{"$ref":"#/components/schemas/PublicApiAdCreativeHookDto"}},"required":["hook"]},"PublicApiAdLinksDto":{"type":"object","properties":{"adLibraryUrl":{"type":"string","nullable":true,"example":"https://www.facebook.com/ads/library/?view_all_page_id=1234567890&id=9876543210"},"landingPageUrl":{"type":"string","nullable":true,"example":"https://example.com/products/summer-sale"}},"required":["adLibraryUrl","landingPageUrl"]},"PublicApiAdShopDto":{"type":"object","properties":{"shopId":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","nullable":true,"example":"Example Shop"},"isPrimary":{"type":"boolean","example":true},"traffic":{"type":"number","nullable":true,"example":45231},"categories":{"nullable":true,"type":"array","items":{"type":"string"},"example":["Fashion","Accessories"]}},"required":["shopId","domain","name","isPrimary","traffic","categories"]},"PublicApiAdPageImpressionsHistoryPointDto":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-04-18"},"totalImpressions":{"type":"number","description":"Facebook page impressions for this date; this is the page-level counterpart to reach-style ad metrics.","example":12340}},"required":["date","totalImpressions"]},"PublicApiAdPageValueHistoryPointDto":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-04-18"},"value":{"type":"number","example":84000}},"required":["date","value"]},"PublicApiAdPageAnalyticsDto":{"type":"object","properties":{"impressionsHistory":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdPageImpressionsHistoryPointDto"},"description":"Historical Facebook page impressions when available; ad-level DTOs may expose comparable Meta Ad Library vocabulary as reach."},"facebookLikesHistory":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdPageValueHistoryPointDto"}},"instagramFollowersHistory":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdPageValueHistoryPointDto"}}},"required":["impressionsHistory","facebookLikesHistory","instagramFollowersHistory"]},"PublicApiAdResolvedFromDto":{"type":"object","properties":{"requestedId":{"type":"string","example":"facebook_2938968053111742","description":"The ad id that was requested."},"reason":{"type":"string","enum":["duplicate_group"],"description":"duplicate_group: the requested ad is a duplicate of the served ad (same collationId); the served ad carries the group's figures."}},"required":["requestedId","reason"]},"PublicApiAdDetailDto":{"type":"object","properties":{"id":{"type":"string","example":"facebook_123456789"},"collationId":{"type":"string","description":"Creative collation identifier when this result represents a deduplicated group of related Meta ads. Pass this value as scan_ad.collation_id to scan the same combined creative shown by search.","example":"3810635369204881"},"platform":{"type":"string","enum":["facebook"],"example":"facebook"},"status":{"type":"string","enum":["active","inactive","unknown"],"description":"For a result with collationId, active means at least one media-backed member ad is active. Without collationId, this is the individual ad status.","example":"active"},"createdAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-18T12:30:00.000Z"},"firstSeenAt":{"type":"string","nullable":true,"format":"date-time","description":"For a result with collationId, the earliest first-seen date across the combined creative members.","example":"2026-04-10T00:00:00.000Z"},"lastSeenAt":{"type":"string","nullable":true,"format":"date-time","description":"For a result with collationId, null while any media-backed member remains active; otherwise the latest member end date.","example":"2026-04-19T00:00:00.000Z"},"daysRunning":{"type":"number","nullable":true,"description":"Indexed running duration in days. For a result with collationId, this is the creative calendar span from the oldest member start to today while any member is active, or to the latest member end otherwise; it does not imply continuous delivery by one ad. Historical backfill is bounded by the available firstSeenAt floor (currently 2018-01-01), so very old ads can share the same maximum/clamped value.","example":9},"media":{"$ref":"#/components/schemas/PublicApiAdMediaDto"},"advertiser":{"$ref":"#/components/schemas/PublicApiAdAdvertiserDto"},"content":{"$ref":"#/components/schemas/PublicApiAdContentSummaryDto"},"metrics":{"$ref":"#/components/schemas/PublicApiAdMetricsDto"},"audience":{"$ref":"#/components/schemas/PublicApiAdAudienceDto"},"rank":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiAdRankDto"}]},"flags":{"$ref":"#/components/schemas/PublicApiAdFlagsDto"},"transcript":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiAdTranscriptDto"}]},"creativeAnalysis":{"$ref":"#/components/schemas/PublicApiAdCreativeAnalysisDto"},"links":{"$ref":"#/components/schemas/PublicApiAdLinksDto"},"shops":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdShopDto"}},"pageAnalytics":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiAdPageAnalyticsDto"}]},"resolvedFrom":{"description":"Present only when the served ad is not the requested one: `id` is then the ad Trendtrack serves for the requested ad's duplicate group.","allOf":[{"$ref":"#/components/schemas/PublicApiAdResolvedFromDto"}]}},"required":["id","platform","status","createdAt","firstSeenAt","lastSeenAt","daysRunning","media","advertiser","content","metrics","audience","rank","flags","transcript","creativeAnalysis","links","shops","pageAnalytics"]},"PublicApiGetAdDetailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiAdDetailDto"}},"required":["requestId","data"]},"PublicApiAdReachHistoryPointDto":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-04-18"},"reach":{"type":"number","nullable":true,"description":"Daily ad reach. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.","example":152340}},"required":["date","reach"]},"PublicApiGetAdReachHistoryResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdReachHistoryPointDto"}}},"required":["requestId","data"]},"PublicApiGoogleAdsAudienceCountriesDto":{"type":"object","properties":{"include":{"example":["US","CA"],"description":"ISO 3166-1 alpha-2 audience countries to include. Google Ads matches targeting.main_country.","type":"array","items":{"type":"string"}},"exclude":{"example":["BR"],"description":"ISO 3166-1 alpha-2 audience countries to exclude. Google Ads matches targeting.main_country.","type":"array","items":{"type":"string"}}}},"QueryPublicApiGoogleAdsRequestDto":{"type":"object","properties":{"search":{"example":["women clothing"],"description":"Optional Google advertiser/domain search terms.","type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","inactive","all"],"default":"all"},"networks":{"type":"array","example":["shopping"],"description":"Google delivery networks. Values are normalized to the casing used by the Google Ads search index.","items":{"type":"string","enum":["search","shopping","maps","youtube","other"]}},"categoryIds":{"example":[24],"description":"Google category ids returned by GET /v1/google-ads/facets/categories. These correspond to the app legacy niches parameter.","type":"array","items":{"type":"number"}},"audienceCountries":{"description":"Audience-country filter. This is intentionally distinct from advertiser/shop creation country.","allOf":[{"$ref":"#/components/schemas/PublicApiGoogleAdsAudienceCountriesDto"}]},"publishedAfter":{"type":"string","format":"date-time"},"publishedBefore":{"type":"string","format":"date-time"},"minDaysRunning":{"type":"number","minimum":0},"maxDaysRunning":{"type":"number","minimum":0},"minReach":{"type":"number","minimum":0},"maxReach":{"type":"number","minimum":0},"sortBy":{"type":"string","enum":["newest","reach","longestRunning"],"default":"newest"},"order":{"type":"string","enum":["asc","desc"],"default":"desc"},"page":{"type":"object","minimum":1,"default":1},"limit":{"type":"object","minimum":1,"maximum":50,"default":25}}},"PublicApiGoogleAdMediaDto":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string","nullable":true},"format":{"type":"string","nullable":true}},"required":["type","url","format"]},"PublicApiGoogleAdAdvertiserLiveAdsDto":{"type":"object","properties":{"google":{"type":"number","nullable":true},"all":{"type":"number","nullable":true}},"required":["google","all"]},"PublicApiGoogleAdAdvertiserDto":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"shopName":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"websiteId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true},"liveAds":{"$ref":"#/components/schemas/PublicApiGoogleAdAdvertiserLiveAdsDto"}},"required":["id","name","shopName","domain","websiteId","logoUrl","liveAds"]},"PublicApiGoogleAdReachDto":{"type":"object","properties":{"value":{"type":"number","nullable":true},"lowerBound":{"type":"number","nullable":true},"upperBound":{"type":"number","nullable":true}},"required":["value","lowerBound","upperBound"]},"PublicApiGoogleAdCountryDto":{"type":"object","properties":{"code":{"type":"string","example":"US"},"percentage":{"type":"number","example":80},"reach":{"type":"number","nullable":true}},"required":["code","percentage"]},"PublicApiGoogleAdAudienceDto":{"type":"object","properties":{"mainCountry":{"type":"string","nullable":true},"countries":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiGoogleAdCountryDto"}},"remarketing":{"type":"boolean"},"interest":{"type":"boolean"}},"required":["mainCountry","countries","remarketing","interest"]},"PublicApiGoogleAdDto":{"type":"object","properties":{"id":{"type":"string","example":"google_123"},"googleAdId":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","inactive"]},"network":{"type":"string","enum":["search","shopping","maps","youtube","other"],"nullable":true},"firstSeenAt":{"type":"string","nullable":true,"format":"date-time"},"lastSeenAt":{"type":"string","nullable":true,"format":"date-time"},"daysRunning":{"type":"number","nullable":true},"media":{"$ref":"#/components/schemas/PublicApiGoogleAdMediaDto"},"advertiser":{"$ref":"#/components/schemas/PublicApiGoogleAdAdvertiserDto"},"reach":{"$ref":"#/components/schemas/PublicApiGoogleAdReachDto"},"audience":{"$ref":"#/components/schemas/PublicApiGoogleAdAudienceDto"}},"required":["id","googleAdId","status","network","firstSeenAt","lastSeenAt","daysRunning","media","advertiser","reach","audience"]},"PublicApiGoogleAdsPaginationDto":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number","nullable":true},"totalPages":{"type":"number","nullable":true}},"required":["page","limit","total","totalPages"]},"PublicApiGoogleAdsQueryResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiGoogleAdDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiGoogleAdsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiGoogleAdsFacetValueDto":{"type":"object","properties":{"value":{"type":"string","example":"shopping"},"label":{"type":"string","example":"Shopping"},"adsCount":{"type":"number"}},"required":["value","label","adsCount"]},"PublicApiGoogleAdsFacetResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiGoogleAdsFacetValueDto"}}},"required":["requestId","data"]},"PublicApiGoogleAdsCategoryFacetDto":{"type":"object","properties":{"id":{"type":"number","example":24},"name":{"type":"string","example":"Women's Clothing"},"path":{"type":"string","nullable":true},"parentId":{"type":"number","nullable":true},"advertiserUsageCount":{"type":"number"}},"required":["id","name","path","parentId","advertiserUsageCount"]},"PublicApiGoogleAdsCategoryFacetPaginationDto":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"}},"required":["limit","offset","total"]},"PublicApiGoogleAdsCategoryFacetsResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiGoogleAdsCategoryFacetDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiGoogleAdsCategoryFacetPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiShopsSortBy":{"type":"string","enum":["monthlyVisits","activeAds","growth30d","productsCount","createdAt","tiktokFollowers","tiktokActiveAds","tiktokTotalPosts","tiktokAvgActiveAds7d","tiktokAvgActiveAds30d","estMonthlySales","unitsSold"]},"PublicApiSortOrder":{"type":"string","enum":["asc","desc"]},"PublicApiShopProfileDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US","nullable":true},"currency":{"type":"string","example":"USD","nullable":true},"isShopifyPlus":{"type":"boolean","example":true,"nullable":true}},"required":["countryCode","currency","isShopifyPlus"]},"PublicApiShopBestSellerDto":{"type":"object","properties":{"imageUrl":{"type":"string","example":"https://cdn.shopify.com/s/files/1/1442/3288/files/PDP_QUIET_WHITE_01-805740.png","nullable":true},"title":{"type":"string","example":"Loop Quiet™ 2","nullable":true},"price":{"type":"number","example":19.95,"nullable":true},"currency":{"type":"string","example":"EUR","nullable":true}},"required":["imageUrl","title","price","currency"]},"PublicApiShopCatalogDto":{"type":"object","properties":{"productsCount":{"type":"number","example":124,"nullable":true},"mainCategory":{"type":"string","example":"Fashion","nullable":true},"bestSellers":{"description":"Top best-selling products for this shop. Capped at 3 items. Sourced from `shopify_best_selling` when available, with fallback to `best_sellers_object` then `best_sellers` image URLs.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopBestSellerDto"}}},"required":["productsCount","mainCategory","bestSellers"]},"PublicApiTimeSeriesPointDto":{"type":"object","properties":{"period":{"type":"string","example":"2026-03-01","description":"ISO date string representing the period start. Month-first (YYYY-MM-DD) for monthly series, week-first for weekly series."},"value":{"type":"number","example":2942350}},"required":["period","value"]},"PublicApiCountryShareDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US"},"share":{"type":"number","example":0.64,"nullable":true}},"required":["countryCode","share"]},"PublicApiShopTrafficDto":{"type":"object","properties":{"monthlyVisits":{"type":"number","example":45231,"nullable":true},"growth30d":{"type":"number","example":0.18,"nullable":true},"history":{"description":"Monthly visits time-series, sorted ascending by period. Capped at the 6 most recent months.","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}},"topCountries":{"description":"Top markets by traffic share (country code + share in [0, 1]). Derived from SimilarWeb geography breakdown when available, otherwise from the `countries` list with null shares.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}}},"required":["monthlyVisits","growth30d","history","topCountries"]},"PublicApiShopSalesDto":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"],"example":"USD","description":"The tracker converts every product price to USD."},"estMonthlySales":{"type":"number","example":222540,"nullable":true,"description":"Estimated revenue over the last 30 days, in whole USD. An estimate from the sales tracker; 0 means the tracker measured no sales."},"unitsSold":{"type":"number","example":1823,"nullable":true,"description":"Units sold over the same 30 days. A floor: the shop sold at least this many."}},"required":["currency","estMonthlySales","unitsSold"]},"PublicApiShopAdvertisingDto":{"type":"object","properties":{"activeAds":{"type":"number","example":12,"nullable":true},"linkedAdvertisersCount":{"type":"number","example":2,"nullable":true},"history":{"description":"Weekly active-ads time-series, sorted ascending by period. Capped at the 26 most recent weekly points (~6 months).","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}},"topCountries":{"description":"Top countries by Meta ads volume (share in [0, 1]). Derived from the shop-level `ads_country_stats` aggregate across all linked advertisers.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}}},"required":["activeAds","linkedAdvertisersCount","history","topCountries"]},"PublicApiShopTikTokProfileMetricsDto":{"type":"object","properties":{"followers":{"type":"number","example":128430,"nullable":true},"totalPosts":{"type":"number","example":342,"nullable":true},"newPosts":{"type":"number","example":12,"nullable":true},"totalViews":{"type":"number","example":9823431,"nullable":true},"totalLikes":{"type":"number","example":456789,"nullable":true}},"required":["followers","totalPosts","newPosts","totalViews","totalLikes"]},"PublicApiShopTikTokActivityDto":{"type":"object","properties":{"activeAds":{"type":"number","example":7,"nullable":true},"totalAds":{"type":"number","example":33,"nullable":true,"description":"Ad posts on the TikTok page at the latest daily snapshot (last 30 days); null when no recent snapshot exists."},"avgActiveAds7d":{"type":"number","example":5.5,"nullable":true},"avgActiveAds30d":{"type":"number","example":4.25,"nullable":true}},"required":["activeAds","totalAds","avgActiveAds7d","avgActiveAds30d"]},"PublicApiShopTikTokSummaryDto":{"type":"object","properties":{"hasTikTok":{"type":"boolean","example":true,"description":"True when the shop has an indexed TikTok page/handle or TikTok rollup activity. This is independent from Meta advertising fields."},"pageId":{"type":"string","example":"6802334614847603717","nullable":true},"handle":{"type":"string","example":"examplebrand","nullable":true},"profileMetrics":{"$ref":"#/components/schemas/PublicApiShopTikTokProfileMetricsDto"},"activity":{"$ref":"#/components/schemas/PublicApiShopTikTokActivityDto"},"lastUpdatedAt":{"type":"string","example":"2026-06-05T08:30:00.000Z","nullable":true,"format":"date-time"}},"required":["hasTikTok","pageId","handle","profileMetrics","activity","lastUpdatedAt"]},"PublicApiShopGoogleAdsReachDto":{"type":"object","properties":{"value":{"type":"number","example":245000,"nullable":true},"label":{"type":"string","example":"Google reported reach","description":"Human-readable reach scope. Google reach is generally available for EU/UK ads; non-EU/UK reach may be absent rather than zero."},"euUkOnly":{"type":"boolean","example":false,"description":"True when the summary was explicitly restricted to Google ads with EU/UK-reported reach."}},"required":["value","label","euUkOnly"]},"PublicApiShopGoogleAdsTopCountryDto":{"type":"object","properties":{"code":{"type":"string","example":"FR","description":"Google Ads audience country code from targeting.main_country. Distinct from shop creation/profile country and traffic market country."},"ads":{"type":"number","example":12,"description":"Number of returned Google Ads creatives in this audience country bucket."},"reach":{"type":"number","example":185000,"description":"Summed Google-reported reach for this audience country bucket. Google reach is only reported for EU/UK-targeted ads where available."}},"required":["code","ads","reach"]},"PublicApiShopGoogleAdsPlatformDto":{"type":"object","properties":{"platform":{"type":"string","example":"SEARCH"},"ads":{"type":"number","example":8}},"required":["platform","ads"]},"PublicApiShopGoogleAdsSummaryDto":{"type":"object","properties":{"status":{"type":"string","enum":["available","unavailable"],"example":"available","description":"available when the Google Ads aggregation succeeded; unavailable when enrichment failed or was intentionally skipped. Shop search still succeeds when unavailable."},"liveAds":{"type":"number","example":14,"nullable":true},"adsLaunched30d":{"type":"number","example":5,"nullable":true,"description":"Google Ads first seen in the most recent 30 days."},"reach":{"$ref":"#/components/schemas/PublicApiShopGoogleAdsReachDto"},"topCountries":{"nullable":true,"description":"Top Google Ads audience countries. Distinct from shop.profile.countryCode and traffic.topCountries.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopGoogleAdsTopCountryDto"}},"platformMix":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PublicApiShopGoogleAdsPlatformDto"}}},"required":["status","liveAds","adsLaunched30d","reach","topCountries","platformMix"]},"PublicApiShopLatestAdDto":{"type":"object","properties":{"id":{"type":"string","example":"facebook_1059447873925448"},"mediaType":{"type":"string","enum":["image","video"],"example":"video"},"mediaUrl":{"type":"string","example":"https://medias.trendtrack.io/video/facebook/1317841346869775.mp4","nullable":true},"thumbnailUrl":{"type":"string","example":"https://medias.trendtrack.io/thumbnails/facebook/1317841346869775.jpg","nullable":true}},"required":["id","mediaType","mediaUrl","thumbnailUrl"]},"PublicApiShopSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","example":"Example Shop","nullable":true},"screenshotUrl":{"type":"string","example":"https://cdn.example.com/screenshots/example.com.png","nullable":true},"createdAt":{"type":"string","example":"2024-01-15T00:00:00.000Z","nullable":true,"format":"date-time"},"profile":{"$ref":"#/components/schemas/PublicApiShopProfileDto"},"catalog":{"$ref":"#/components/schemas/PublicApiShopCatalogDto"},"traffic":{"$ref":"#/components/schemas/PublicApiShopTrafficDto"},"sales":{"nullable":true,"description":"Current sales estimate. Null when the sales tracker does not follow the shop. Present on shop-search rows; omitted by the deprecated favorites endpoints.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSalesDto"}]},"advertising":{"$ref":"#/components/schemas/PublicApiShopAdvertisingDto"},"tiktok":{"$ref":"#/components/schemas/PublicApiShopTikTokSummaryDto"},"googleAds":{"description":"Compact best-effort Google Ads summary hydrated for returned shop-search pages. When aggregation fails, status is unavailable and metric values are null. Present on shop-search rows; omitted by older summary producers that do not run Google Ads hydration.","allOf":[{"$ref":"#/components/schemas/PublicApiShopGoogleAdsSummaryDto"}]},"latestAds":{"description":"Up to 3 most recent Meta ads published by the shop.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopLatestAdDto"}}},"required":["id","domain","name","screenshotUrl","createdAt","profile","catalog","traffic","advertising","tiktok","latestAds"]},"PublicApiPaginationDto":{"type":"object","properties":{"limit":{"type":"number","example":32},"offset":{"type":"number","example":0},"total":{"type":"number","example":128}},"required":["limit","offset","total"]},"PublicApiGetShopsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiShopSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiShopsQuerySearchType":{"type":"string","enum":["domain","productName","shopContains"],"description":"Search mode. domain performs exact domain/related-domain matching from a domain or URL, productName searches indexed product text, and shopContains matches website text, keeping the 10,000 most relevant shops before filters and sorting are applied."},"PublicApiShopsQuerySortBy":{"type":"string","enum":["relevance","monthlyVisits","activeAds","growth30d","productsCount","createdAt","tiktokFollowers","tiktokActiveAds","tiktokTotalPosts","tiktokAvgActiveAds7d","tiktokAvgActiveAds30d","estMonthlySales","unitsSold"],"description":"Sort key for the advanced shops query surface. relevance orders by monthlyVisits, as in the Trendtrack app: the search text filters shops but does not rank them."},"PublicApiTrafficGrowthPeriod":{"type":"string","enum":["last30d","last90d","last180d"],"description":"Indexed traffic growth window."},"PublicApiQueryFilterComparison":{"type":"string","enum":["greater","lower"],"description":"Comparison applied to the growth threshold. Use `greater` for gte and `lower` for lte semantics."},"PublicApiQueryFilterOperator":{"type":"string","enum":["and","or"],"description":"Logical operator linking this condition to the next one in the array."},"PublicApiTrafficGrowthConditionDto":{"type":"object","properties":{"period":{"example":"last30d","description":"Indexed traffic growth window.","allOf":[{"$ref":"#/components/schemas/PublicApiTrafficGrowthPeriod"}]},"value":{"type":"number","example":20,"description":"Minimum or maximum growth threshold, expressed as a percentage."},"comparison":{"example":"greater","description":"Comparison applied to the growth threshold. Use `greater` for gte and `lower` for lte semantics.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterComparison"}]},"operator":{"example":"or","description":"Logical operator linking this condition to the next one in the array.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterOperator"}]}},"required":["period","comparison"]},"PublicApiAdsGrowthPeriod":{"type":"string","enum":["last7d","last30d","last90d"],"description":"Indexed ads growth window."},"PublicApiAdsGrowthConditionDto":{"type":"object","properties":{"period":{"example":"last7d","description":"Indexed ads growth window.","allOf":[{"$ref":"#/components/schemas/PublicApiAdsGrowthPeriod"}]},"value":{"type":"number","example":40,"description":"Minimum or maximum growth threshold, expressed as a percentage."},"comparison":{"example":"greater","description":"Comparison applied to the growth threshold. Use `greater` for gte and `lower` for lte semantics.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterComparison"}]},"operator":{"example":"or","description":"Comparison operator for this rule. Allowed values: `and`, `or`.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterOperator"}]}},"required":["period","comparison"]},"PublicApiReachGrowthPeriod":{"type":"string","enum":["last7d","last14d","last30d","last60d","last90d"],"description":"Indexed reach growth window."},"PublicApiReachGrowthConditionDto":{"type":"object","properties":{"period":{"example":"last30d","description":"Indexed reach growth window.","allOf":[{"$ref":"#/components/schemas/PublicApiReachGrowthPeriod"}]},"value":{"type":"number","example":35,"description":"Minimum or maximum growth threshold, expressed as a percentage."},"comparison":{"example":"greater","description":"Comparison applied to the growth threshold. Use `greater` for gte and `lower` for lte semantics.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterComparison"}]},"operator":{"example":"and","description":"Comparison operator for this rule. Allowed values: `and`, `or`.","allOf":[{"$ref":"#/components/schemas/PublicApiQueryFilterOperator"}]}},"required":["period","comparison"]},"PublicApiShopsDtcRegion":{"type":"string","enum":["all","us","eu"],"description":"Optional DTC preset. all means any indexed DTC shop, while us and eu also apply the corresponding creation-country subset used by the app."},"QueryPublicApiShopsRequestDto":{"type":"object","properties":{"search":{"type":"string","example":"https://www.allbirds.com/products","description":"Optional search string. For searchType=\"domain\", send a domain or URL for exact domain/related-domain matching. For broad website text search, use shopContains. For product text, use productName. Do not send unsupported legacy keys name, domain, or domains."},"searchType":{"example":"domain","description":"Search mode. domain performs exact domain/related-domain matching from a domain or URL, productName searches indexed product text, and shopContains matches website text, keeping the 10,000 most relevant shops before filters and sorting are applied.","allOf":[{"$ref":"#/components/schemas/PublicApiShopsQuerySearchType"}]},"sortBy":{"example":"relevance","description":"Sort key for the advanced shops query surface. relevance orders by monthlyVisits, as in the Trendtrack app: the search text filters shops but does not rank them.","allOf":[{"$ref":"#/components/schemas/PublicApiShopsQuerySortBy"}]},"order":{"example":"desc","description":"Enum value accepted by this request. Allowed values: `asc`, `desc`.","allOf":[{"$ref":"#/components/schemas/PublicApiSortOrder"}]},"offset":{"type":"number","example":0,"minimum":0},"limit":{"type":"number","example":32,"minimum":1,"maximum":100},"categoryIds":{"example":[166,417],"description":"Optional category ids used by the current shop discovery index.","type":"array","items":{"type":"number"}},"minEstimatedRevenue":{"type":"number","example":10000,"minimum":0,"deprecated":true,"description":"Deprecated and rejected with 400: use minMonthlySales, read from the sales tracker."},"maxEstimatedRevenue":{"type":"number","example":500000,"minimum":0,"deprecated":true,"description":"Deprecated and rejected with 400: use maxMonthlySales, read from the sales tracker."},"minMonthlySales":{"type":"number","example":10000,"minimum":0,"description":"Minimum estimated revenue over the last 30 days, in USD (sales tracker). Shops the tracker does not follow are excluded."},"maxMonthlySales":{"type":"number","example":500000,"minimum":0,"description":"Maximum estimated revenue over the last 30 days, in USD (sales tracker)."},"minUnitsSold":{"type":"number","example":500,"minimum":0,"description":"Minimum units sold over the last 30 days (sales tracker). Shops the tracker does not follow are excluded."},"maxUnitsSold":{"type":"number","example":10000,"minimum":0,"description":"Maximum units sold over the last 30 days (sales tracker)."},"minMonthlyVisits":{"type":"number","example":5000,"minimum":0},"maxMonthlyVisits":{"type":"number","example":500000,"minimum":0},"minProductsCount":{"type":"number","example":10,"minimum":0},"maxProductsCount":{"type":"number","example":500,"minimum":0},"createdAfter":{"type":"string","format":"date","example":"2024-01-01"},"createdBefore":{"type":"string","format":"date","example":"2024-12-31"},"mainMarketCountries":{"example":["US","CA"],"description":"Optional main audience-market filter using uppercase ISO 3166-1 alpha-2 country codes matched against the indexed main_market field.","type":"array","items":{"type":"string"}},"marketCountries":{"example":["CA","GB"],"description":"Optional audience-market filter for shops where these countries appear among the indexed traffic markets.","type":"array","items":{"type":"string"}},"excludeMarketCountries":{"example":["DE"],"type":"array","items":{"type":"string"}},"minBestSellerPrice":{"type":"number","example":20,"minimum":0},"maxBestSellerPrice":{"type":"number","example":150,"minimum":0},"minActiveAds":{"type":"number","example":5,"minimum":0,"description":"Optional minimum active ads filter. The metric follows adsTimePeriod."},"maxActiveAds":{"type":"number","example":50,"minimum":0,"description":"Optional maximum active ads filter. The metric follows adsTimePeriod."},"adsTimePeriod":{"example":"last24h","description":"Time window accepted by this request. Allowed values: `last24h`, `last7d`, `last30d`.","allOf":[{"$ref":"#/components/schemas/PublicApiAdsTimePeriod"}]},"hasTikTok":{"type":"boolean","example":true,"description":"Optional TikTok presence filter backed by the legacy flat shop index. true requires an indexed TikTok page or handle; false excludes shops with one."},"minTikTokFollowers":{"type":"number","example":10000,"minimum":0},"maxTikTokFollowers":{"type":"number","example":500000,"minimum":0},"minTikTokActiveAds":{"type":"number","example":5,"minimum":0},"maxTikTokActiveAds":{"type":"number","example":50,"minimum":0},"minTikTokTotalPosts":{"type":"number","example":20,"minimum":0},"maxTikTokTotalPosts":{"type":"number","example":1000,"minimum":0},"isShopifyPlus":{"type":"boolean","example":true},"trafficGrowth":{"description":"Traffic growth filters. Each condition uses `period`, `comparison`, and `value`; optional `operator` links the condition to the next one.","example":[{"period":"last30d","comparison":"greater","value":20}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiTrafficGrowthConditionDto"}},"adsGrowth":{"description":"Ads growth filters. Each condition uses `period`, `comparison`, and `value`; optional `operator` links the condition to the next one.","example":[{"period":"last7d","comparison":"greater","value":15}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdsGrowthConditionDto"}},"pageReachGrowth":{"description":"Page reach growth filters. Each condition uses `period`, `comparison`, and `value`; optional `operator` links the condition to the next one.","example":[{"period":"last30d","comparison":"greater","value":40}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiReachGrowthConditionDto"}},"adReachGrowth":{"description":"Ad reach growth filters. Each condition uses `period`, `comparison`, and `value`; optional `operator` links the condition to the next one.","example":[{"period":"last7d","comparison":"lower","value":5}],"type":"array","items":{"$ref":"#/components/schemas/PublicApiReachGrowthConditionDto"}},"creationCountries":{"example":["FR","DE"],"type":"array","items":{"type":"string"}},"excludeCreationCountries":{"example":["CN"],"type":"array","items":{"type":"string"}},"displayInTrending":{"type":"boolean","example":true,"description":"When true, restricts results to shops visible in the Trendtrack trending shops feed."},"themeIds":{"example":["29bcbf64-9679-439a-9f07-7ad230b6ca16"],"description":"Optional canonical Shopify theme UUIDs backed by the current website discovery index. Use /v1/facets/themes to resolve display names.","type":"array","items":{"type":"string","format":"uuid"}},"pixelIds":{"example":["ffe94cf7-e81d-5c43-9253-359117b1a544"],"description":"Optional canonical pixel UUIDs backed by the current website discovery index. Use /v1/facets/pixels to resolve display names.","type":"array","items":{"type":"string","format":"uuid"}},"excludePixelIds":{"example":["fb3d434c-8fb6-5687-ab39-82c588bdbefa"],"description":"Optional canonical pixel UUIDs to exclude. Use /v1/facets/pixels to resolve display names.","type":"array","items":{"type":"string","format":"uuid"}},"shopifyAppIds":{"example":["41c143a7-0000-4000-8000-000000000000","52d254b8-0000-4000-8000-000000000000"],"description":"Optional canonical Shopify app UUIDs backed by the current website discovery index. Use /v1/facets/shopify-apps to resolve names to ids.","type":"array","items":{"type":"string","format":"uuid"}},"excludeShopifyAppIds":{"example":["63e365c9-0000-4000-8000-000000000000"],"description":"Optional canonical Shopify app UUIDs to exclude. Use /v1/facets/shopify-apps to resolve names to ids.","type":"array","items":{"type":"string","format":"uuid"}},"minTrustpilotRating":{"type":"number","example":4.2,"minimum":0},"maxTrustpilotRating":{"type":"number","example":4.9,"minimum":0},"minTrustpilotReviewCount":{"type":"number","example":100,"minimum":0},"maxTrustpilotReviewCount":{"type":"number","example":5000,"minimum":0},"languages":{"example":["en","fr"],"type":"array","items":{"type":"string"}},"currencies":{"example":["USD","EUR"],"type":"array","items":{"type":"string"}},"dtcRegion":{"example":"eu","description":"Optional DTC preset. all means any indexed DTC shop, while us and eu also apply the corresponding creation-country subset used by the app.","allOf":[{"$ref":"#/components/schemas/PublicApiShopsDtcRegion"}]}}},"PublicApiSimilarShopsSortBy":{"type":"string","enum":["relevance","monthlyVisits","activeAds","growth30d","productsCount","createdAt"]},"PublicApiSimilarShopItemDto":{"type":"object","properties":{"shop":{"$ref":"#/components/schemas/PublicApiShopSummaryDto"},"similarityScore":{"type":"number","example":0.9137}},"required":["shop","similarityScore"]},"PublicApiGetSimilarShopsMetaDto":{"type":"object","properties":{"shopExists":{"type":"boolean","example":true,"description":"False when the resolved shop/domain does not exist in the similar shops engine."}},"required":["shopExists"]},"PublicApiGetSimilarShopsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSimilarShopItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiGetSimilarShopsMetaDto"}},"required":["requestId","data","pagination","meta"]},"PublicApiProductImageSearchRequestDto":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Image file (JPEG, PNG or WEBP, 10 MB max), sent as multipart/form-data. Provide exactly one of image, imageUrl or searchId."},"imageUrl":{"type":"string","example":"https://cdn.shopify.com/s/files/1/0000/products/lamp.jpg","maxLength":2048,"description":"Public http(s) URL of the image. The server downloads it (10 MB max)."},"searchId":{"type":"string","format":"uuid","description":"searchId returned by a previous image search of this workspace. Replays the same image to read its next pages without sending it again."},"offset":{"type":"number","example":0,"minimum":0,"default":0},"limit":{"type":"number","example":20,"minimum":1,"maximum":100,"default":20},"groupBrands":{"type":"boolean","example":true,"default":true,"description":"Count the storefronts of one brand (same root domain across countries, or the same Shopify store on several domains) as one shop. False keeps every storefront apart; the same store on several domains always counts once."},"maxPerShop":{"type":"number","example":1,"minimum":0,"maximum":10,"default":1,"description":"Products returned per shop (or brand), most similar first; 0 = no cap. A product repeated in one shop (variants, duplicate photos) is always returned once."}}},"PublicApiImageMatchedProductDto":{"type":"object","properties":{"shopifyId":{"type":"number","nullable":true,"example":7429183447215},"title":{"type":"string","nullable":true,"example":"Moon lamp"},"imageUrl":{"type":"string","nullable":true},"price":{"type":"number","nullable":true,"example":29.9},"currency":{"type":"string","nullable":true,"example":"USD"},"similarityScore":{"type":"number","example":0.91,"description":"Cosine similarity between the query image and the product image (0.7 to 1)."}},"required":["shopifyId","title","imageUrl","price","currency","similarityScore"]},"PublicApiProductImageSearchItemDto":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/PublicApiImageMatchedProductDto"},"shop":{"$ref":"#/components/schemas/PublicApiShopSummaryDto"}},"required":["product","shop"]},"PublicApiImageSearchMetaDto":{"type":"object","properties":{"searchId":{"type":"string","nullable":true,"format":"uuid","description":"Send it back instead of the image to read the next pages. Null when the search could not be kept."}},"required":["searchId"]},"PublicApiProductImageSearchResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiProductImageSearchItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiImageSearchMetaDto"}},"required":["requestId","data","pagination","meta"]},"PublicApiShopImageSearchRequestDto":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Image file (JPEG, PNG or WEBP, 10 MB max), sent as multipart/form-data. Provide exactly one of image, imageUrl or searchId."},"imageUrl":{"type":"string","example":"https://cdn.shopify.com/s/files/1/0000/products/lamp.jpg","maxLength":2048,"description":"Public http(s) URL of the image. The server downloads it (10 MB max)."},"searchId":{"type":"string","format":"uuid","description":"searchId returned by a previous image search of this workspace. Replays the same image to read its next pages without sending it again."},"offset":{"type":"number","example":0,"minimum":0,"default":0},"limit":{"type":"number","example":20,"minimum":1,"maximum":100,"default":20},"groupBrands":{"type":"boolean","example":true,"default":true,"description":"Count the storefronts of one brand (same root domain across countries, or the same Shopify store on several domains) as one shop. False keeps every storefront apart; the same store on several domains always counts once."},"productsPerShop":{"type":"number","example":3,"minimum":0,"maximum":10,"default":3,"description":"Most similar matching products returned with each shop."}}},"PublicApiImageStorefrontDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","example":"fridoorthotics.com"},"name":{"type":"string","nullable":true},"monthlyVisits":{"type":"number","nullable":true},"activeAds":{"type":"number","nullable":true}},"required":["id","domain","name","monthlyVisits","activeAds"]},"PublicApiShopImageSearchItemDto":{"type":"object","properties":{"shop":{"description":"The storefront of the brand with the most active ads.","allOf":[{"$ref":"#/components/schemas/PublicApiShopSummaryDto"}]},"otherStorefronts":{"description":"The brand's other storefronts selling matching products (other countries or domains). Empty when groupBrands is false, unless one store is served on several domains.","type":"array","items":{"$ref":"#/components/schemas/PublicApiImageStorefrontDto"}},"bestSimilarityScore":{"type":"number","example":0.93},"matchingProducts":{"type":"number","example":4,"description":"Distinct products of the shop (or brand) that look like the image."},"products":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiImageMatchedProductDto"}}},"required":["shop","otherStorefronts","bestSimilarityScore","matchingProducts","products"]},"PublicApiShopImageSearchResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiShopImageSearchItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiImageSearchMetaDto"}},"required":["requestId","data","pagination","meta"]},"PublicApiLinkedAdvertiserSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"1234567890"},"platform":{"type":"string","enum":["facebook"],"example":"facebook"},"facebookPageId":{"type":"string","example":"1234567890"},"name":{"type":"string","example":"Acme Brand","nullable":true},"isPrimary":{"type":"boolean","example":true},"activeAds":{"type":"number","example":12,"nullable":true}},"required":["id","platform","facebookPageId","name","isPrimary","activeAds"]},"PublicApiGetShopAdvertisersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiLinkedAdvertiserSummaryDto"}}},"required":["requestId","data"]},"PublicApiShopSocialsHistoryPeriod":{"type":"string","enum":["day","week","month"]},"PublicApiShopSocialsHistoryDataDto":{"type":"object","properties":{"facebook":{"description":"Facebook follower snapshots ordered ascending by period. Empty when no Facebook page is linked to the shop.","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}},"instagram":{"description":"Instagram follower snapshots ordered ascending by period. Empty when the linked Facebook page has no connected Instagram account.","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}}},"required":["facebook","instagram"]},"PublicApiGetShopSocialsHistoryResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"req_01JN3C9Q2K5X9Y6V7W8Z1A2B3C"},"data":{"$ref":"#/components/schemas/PublicApiShopSocialsHistoryDataDto"}},"required":["requestId","data"]},"PublicApiShopSalesHistoryPeriod":{"type":"string","enum":["day","week","month"]},"PublicApiShopSalesHistoryEntryDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-09-29","description":"UTC day of the reading (YYYY-MM-DD)."},"estMonthlySales":{"type":"number","example":222540,"nullable":true,"description":"Estimated revenue over the 30 days before `date`, in whole USD. Not the revenue of that single day."},"estMonthlySalesMin":{"type":"number","example":170450,"nullable":true},"estMonthlySalesMax":{"type":"number","example":274103,"nullable":true},"unitsSold":{"type":"number","example":1823,"nullable":true,"description":"Units sold over the same 30 days, as a floor."}},"required":["date","estMonthlySales","estMonthlySalesMin","estMonthlySalesMax","unitsSold"]},"PublicApiShopSalesHistoryDataDto":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"],"example":"USD"},"history":{"description":"Readings ordered ascending by date, ending on the current estimate. Empty when the sales tracker does not follow the shop. The history starts on 2026-09-18.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopSalesHistoryEntryDto"}}},"required":["currency","history"]},"PublicApiGetShopSalesHistoryResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"req_01JN3C9Q2K5X9Y6V7W8Z1A2B3C"},"data":{"$ref":"#/components/schemas/PublicApiShopSalesHistoryDataDto"}},"required":["requestId","data"]},"PublicApiShopProductsSortBy":{"type":"string","enum":["popularity","price","createdAt"]},"PublicApiShopProductDto":{"type":"object","properties":{"id":{"type":"string","example":"7869034926321","nullable":true,"description":"Upstream Shopify numeric product id (as a string)."},"title":{"type":"string","example":"Loop Quiet™ 2","nullable":true},"handle":{"type":"string","example":"loop-quiet-2","nullable":true,"description":"Shopify product handle (URL slug)."},"imageUrl":{"type":"string","example":"https://cdn.shopify.com/s/files/1/1442/3288/files/PDP_QUIET_WHITE_01-805740.png","nullable":true},"productUrl":{"type":"string","example":"https://loopearplugs.com/products/loop-quiet-2","nullable":true},"price":{"type":"number","example":19.95,"nullable":true},"currency":{"type":"string","example":"EUR","nullable":true},"rank":{"type":"number","example":1,"nullable":true,"description":"Position of the product in the shop’s best-seller list, with 1 being the best seller."},"createdAt":{"type":"string","example":"2024-08-20T00:00:00.000Z","nullable":true,"format":"date-time","description":"Shopify product creation date."},"publishedAt":{"type":"string","example":"2024-08-22T00:00:00.000Z","nullable":true,"format":"date-time","description":"Shopify product publication date."}},"required":["id","title","handle","imageUrl","productUrl","price","currency","rank","createdAt","publishedAt"]},"PublicApiGetShopProductsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"req_01JN3C9Q2K5X9Y6V7W8Z1A2B3C"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiShopProductDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiShopDetailProfileDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US","nullable":true},"currency":{"type":"string","example":"USD","nullable":true},"isShopifyPlus":{"type":"boolean","example":true,"nullable":true},"defaultLanguage":{"type":"string","example":"en","nullable":true}},"required":["countryCode","currency","isShopifyPlus","defaultLanguage"]},"PublicApiShopTrustpilotDto":{"type":"object","properties":{"rating":{"type":"number","example":4.7,"nullable":true},"reviewCount":{"type":"number","example":1834,"nullable":true},"brandName":{"type":"string","example":"Loop Earplugs","nullable":true},"brandLogo":{"type":"string","example":"https://s3-eu-west-1.amazonaws.com/tpd/logos/...png","nullable":true},"url":{"type":"string","example":"https://www.trustpilot.com/review/loopearplugs.com","nullable":true}},"required":["rating","reviewCount","brandName","brandLogo","url"]},"PublicApiShopSocialNetworkDto":{"type":"object","properties":{"handle":{"type":"string","example":"loopearplugs","nullable":true,"description":"Public handle / username used by the shop on this network."},"followers":{"type":"number","example":12843,"nullable":true,"description":"Current follower count. Only populated for Facebook and Instagram today; other networks are tracked as handle-only."},"growth30d":{"type":"number","example":0.042,"nullable":true,"description":"Relative follower growth over the most recent ~30 days. Null when the follower count is unknown or there is no comparable data point 30 days ago."}},"required":["handle","followers","growth30d"]},"PublicApiShopSocialsDto":{"type":"object","properties":{"facebook":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"instagram":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"tiktok":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"youtube":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"pinterest":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"linkedin":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]},"twitter":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialNetworkDto"}]}},"required":["facebook","instagram","tiktok","youtube","pinterest","linkedin","twitter"]},"PublicApiShopDetailCatalogDto":{"type":"object","properties":{"productsCount":{"type":"number","example":124,"nullable":true},"mainCategory":{"type":"string","example":"Fashion","nullable":true},"bestSellers":{"description":"Top best-selling products for this shop. Capped at 3 items. Sourced from `shopify_best_selling` when available, with fallback to `best_sellers_object` then `best_sellers` image URLs.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopBestSellerDto"}},"categories":{"example":["Fashion","Accessories"],"type":"array","items":{"type":"string"}},"myShopifyDomain":{"type":"string","example":"loopearplugs.myshopify.com","nullable":true}},"required":["productsCount","mainCategory","bestSellers","categories","myShopifyDomain"]},"PublicApiShopDetailTrafficDto":{"type":"object","properties":{"monthlyVisits":{"type":"number","example":45231,"nullable":true},"growth30d":{"type":"number","example":0.18,"nullable":true},"history":{"description":"Monthly visits time-series, sorted ascending by period. Capped at the 6 most recent months.","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}},"topCountries":{"description":"Top markets by traffic share (country code + share in [0, 1]). Derived from SimilarWeb geography breakdown when available, otherwise from the `countries` list with null shares.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}},"growth90d":{"type":"number","example":0.32,"nullable":true},"growth180d":{"type":"number","example":0.41,"nullable":true},"mainMarkets":{"description":"Alias of `topCountries` kept for backwards compatibility with the detail endpoint.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}}},"required":["monthlyVisits","growth30d","history","topCountries","growth90d","growth180d","mainMarkets"]},"PublicApiShopDetailSalesDto":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"],"example":"USD","description":"The tracker converts every product price to USD."},"estMonthlySales":{"type":"number","example":222540,"nullable":true,"description":"Estimated revenue over the last 30 days, in whole USD. An estimate from the sales tracker; 0 means the tracker measured no sales."},"unitsSold":{"type":"number","example":1823,"nullable":true,"description":"Units sold over the same 30 days. A floor: the shop sold at least this many."},"estMonthlySalesMin":{"type":"number","example":170450,"nullable":true,"description":"Low end of the 30-day revenue estimate, in whole USD."},"estMonthlySalesMax":{"type":"number","example":274103,"nullable":true,"description":"High end of the 30-day revenue estimate, in whole USD."}},"required":["currency","estMonthlySales","unitsSold","estMonthlySalesMin","estMonthlySalesMax"]},"PublicApiShopAdvertisingSummaryDto":{"type":"object","properties":{"activeAds":{"type":"number","example":12,"nullable":true},"avgActiveAds30d":{"type":"number","example":9.4,"nullable":true},"reach30d":{"type":"number","example":102300,"nullable":true,"description":"Current implementation uses the aggregated 30-day EU reach of linked Facebook pages when available."},"countryDistribution":{"description":"Country distribution derived from linked Facebook advertisers reach. Use `shop.advertising.topCountries` / `adsCountryStats` for the shop-level ads_country_stats breakdown.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}}},"required":["activeAds","avgActiveAds30d","reach30d","countryDistribution"]},"PublicApiShopDetailAdvertisingDto":{"type":"object","properties":{"activeAds":{"type":"number","example":12,"nullable":true},"linkedAdvertisersCount":{"type":"number","example":2,"nullable":true},"history":{"description":"Weekly active-ads time-series, sorted ascending by period. Capped at the 26 most recent weekly points (~6 months).","type":"array","items":{"$ref":"#/components/schemas/PublicApiTimeSeriesPointDto"}},"topCountries":{"description":"Top countries by Meta ads volume (share in [0, 1]). Derived from the shop-level `ads_country_stats` aggregate across all linked advertisers.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}},"linkedAdvertisers":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiLinkedAdvertiserSummaryDto"}},"summary":{"$ref":"#/components/schemas/PublicApiShopAdvertisingSummaryDto"},"adsCountryStats":{"description":"Shop-level Meta ads country distribution from `ads_country_stats`. Distinct from `summary.countryDistribution`, which is derived from linked Facebook page reach.","type":"array","items":{"$ref":"#/components/schemas/PublicApiCountryShareDto"}}},"required":["activeAds","linkedAdvertisersCount","history","topCountries","linkedAdvertisers","summary","adsCountryStats"]},"PublicApiShopAppDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"41c143a7-0000-4000-8000-000000000000","description":"Canonical Shopify app UUID. Matches the `shopifyAppIds` filter accepted by POST /v1/shops/query."},"label":{"type":"string","example":"Judge.me","nullable":true},"iconUrl":{"type":"string","example":"https://cdn.shopify.com/app-store/listing_images/abc/icon.png","nullable":true,"description":"Absolute URL to the Shopify app icon as published by the Shopify app store. May be null when the vendor has not provided an icon."}},"required":["id","label","iconUrl"]},"PublicApiShopPixelDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"002d1031-2a33-42c6-9b4a-c5db2349ecec","description":"Canonical pixel UUID. Matches the `pixelIds` filter accepted by POST /v1/shops/query."},"name":{"type":"string","example":"Meta Pixel","nullable":true},"iconUrl":{"type":"string","example":"https://trendtrack.r2.cloudflarestorage.com/technology_icons/MetaPixel.png?...signature","nullable":true,"description":"Pre-signed CDN URL for the pixel icon. URLs expire after ~24h; re-fetch the shop detail to refresh them."},"categories":{"example":[],"description":"Compatibility field. Canonical pixel records currently do not define categories, so this is normally empty.","type":"array","items":{"type":"string"}}},"required":["id","name","iconUrl","categories"]},"PublicApiShopTechnologyDto":{"type":"object","properties":{"theme":{"type":"string","example":"Prestige","nullable":true,"description":"Canonical Shopify theme display name from the shop technology profile."},"apps":{"description":"Shopify apps detected on the shop, with vendor icons.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopAppDto"}},"pixels":{"description":"Pixels detected on the shop, resolved to human-readable names and icons via the public technologies vocabulary.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopPixelDto"}}},"required":["theme","apps","pixels"]},"PublicApiShopTikTokDetailDto":{"type":"object","properties":{"hasTikTok":{"type":"boolean","example":true,"description":"True when the shop has an indexed TikTok page/handle or TikTok rollup activity. This is independent from Meta advertising fields."},"pageId":{"type":"string","example":"6802334614847603717","nullable":true},"handle":{"type":"string","example":"examplebrand","nullable":true},"profileMetrics":{"$ref":"#/components/schemas/PublicApiShopTikTokProfileMetricsDto"},"activity":{"$ref":"#/components/schemas/PublicApiShopTikTokActivityDto"},"lastUpdatedAt":{"type":"string","example":"2026-06-05T08:30:00.000Z","nullable":true,"format":"date-time"}},"required":["hasTikTok","pageId","handle","profileMetrics","activity","lastUpdatedAt"]},"PublicApiShopDetailDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8"},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","example":"Example Shop","nullable":true},"screenshotUrl":{"type":"string","example":"https://cdn.example.com/screenshots/example.com.png","nullable":true},"createdAt":{"type":"string","example":"2024-01-15T00:00:00.000Z","nullable":true,"format":"date-time"},"profile":{"$ref":"#/components/schemas/PublicApiShopDetailProfileDto"},"trustpilot":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopTrustpilotDto"}]},"socials":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopSocialsDto"}]},"catalog":{"$ref":"#/components/schemas/PublicApiShopDetailCatalogDto"},"traffic":{"$ref":"#/components/schemas/PublicApiShopDetailTrafficDto"},"sales":{"nullable":true,"description":"Current sales estimate. Null when the sales tracker does not follow the shop. For the daily history, call GET /v1/shops/{shopId}/sales/history.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiShopDetailSalesDto"}]},"advertising":{"$ref":"#/components/schemas/PublicApiShopDetailAdvertisingDto"},"technology":{"$ref":"#/components/schemas/PublicApiShopTechnologyDto"},"tiktok":{"$ref":"#/components/schemas/PublicApiShopTikTokDetailDto"},"latestAds":{"description":"Up to 3 most recent Meta ads published by the shop.","type":"array","items":{"$ref":"#/components/schemas/PublicApiShopLatestAdDto"}},"similarShops":{"description":"Preview of up to 6 shops ranked by similarity (relevance desc). For the full paginated list, call GET /v1/shops/{identifier}/similar using either the domain or public shop id.","type":"array","items":{"$ref":"#/components/schemas/PublicApiSimilarShopItemDto"}}},"required":["id","domain","name","screenshotUrl","createdAt","profile","trustpilot","socials","catalog","traffic","sales","advertising","technology","tiktok","latestAds","similarShops"]},"PublicApiGetShopResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiShopDetailDto"}},"required":["requestId","data"]},"Object":{"type":"object","properties":{}},"PublicApiTikTokMediaItemDto":{"type":"object","properties":{"type":{"type":"string","enum":["image","video","carousel","unknown"],"example":"video"},"url":{"type":"string","nullable":true},"order":{"type":"number","nullable":true}},"required":["type","url","order"]},"PublicApiTikTokMediaDto":{"type":"object","properties":{"type":{"type":"string","enum":["image","video","carousel","unknown"],"example":"video"},"thumbnailUrl":{"type":"string","nullable":true},"mediaUrl":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"medias":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiTikTokMediaItemDto"}},"durationSec":{"type":"number","nullable":true},"mediaCount":{"type":"number","nullable":true},"imageCount":{"type":"number","nullable":true}},"required":["type","thumbnailUrl","mediaUrl","videoUrl","imageUrls","medias","durationSec","mediaCount","imageCount"]},"PublicApiTikTokMusicDto":{"type":"object","properties":{"id":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"author":{"type":"string","nullable":true}},"required":["id","title","author"]},"PublicApiTikTokContentDto":{"type":"object","properties":{"description":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"hashtags":{"type":"array","items":{"type":"string"}},"music":{"$ref":"#/components/schemas/PublicApiTikTokMusicDto"}},"required":["description","language","category","hashtags","music"]},"PublicApiTikTokMetricsDto":{"type":"object","properties":{"views":{"type":"number","nullable":true},"likes":{"type":"number","nullable":true},"comments":{"type":"number","nullable":true},"saves":{"type":"number","nullable":true},"shares":{"type":"number","nullable":true},"reposts":{"type":"number","nullable":true},"engagementRate":{"type":"number","nullable":true,"description":"Percentage, not fraction."},"rank":{"type":"number","nullable":true},"rankPercent":{"type":"number","nullable":true},"relevanceScore":{"type":"number","nullable":true},"deltaRank3d":{"type":"number","nullable":true},"deltaRank7d":{"type":"number","nullable":true},"deltaRank14d":{"type":"number","nullable":true},"deltaRank30d":{"type":"number","nullable":true}},"required":["views","likes","comments","saves","shares","reposts","engagementRate","rank","rankPercent","relevanceScore","deltaRank3d","deltaRank7d","deltaRank14d","deltaRank30d"]},"PublicApiTikTokProfileDto":{"type":"object","properties":{"id":{"type":"string","nullable":true},"handle":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"bioUrl":{"type":"string","nullable":true},"accountType":{"type":"string","nullable":true},"secUid":{"type":"string","nullable":true},"followers":{"type":"number","nullable":true},"following":{"type":"number","nullable":true},"totalTikToks":{"type":"number","nullable":true},"newTikToks":{"type":"number","nullable":true},"percentAds":{"type":"number","nullable":true},"views":{"type":"number","nullable":true},"likes":{"type":"number","nullable":true},"pageCreation":{"type":"string","nullable":true}},"required":["id","handle","name","avatarUrl","bio","bioUrl","accountType","secUid","followers","following","totalTikToks","newTikToks","percentAds","views","likes","pageCreation"]},"PublicApiTikTokShopDto":{"type":"object","properties":{"id":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"countryCode":{"type":"string","nullable":true},"monthlyVisits":{"type":"number","nullable":true},"trafficGrowth30d":{"type":"number","nullable":true},"productsCount":{"type":"number","nullable":true},"googleCategoryIds":{"type":"array","items":{"type":"number"}}},"required":["id","domain","name","logoUrl","faviconUrl","countryCode","monthlyVisits","trafficGrowth30d","productsCount","googleCategoryIds"]},"PublicApiTikTokPinDto":{"type":"object","properties":{"isCurrent":{"type":"boolean","nullable":true},"firstPinnedAt":{"type":"string","nullable":true},"lastPinnedAt":{"type":"string","nullable":true},"lastUnpinnedAt":{"type":"string","nullable":true}},"required":["isCurrent","firstPinnedAt","lastPinnedAt","lastUnpinnedAt"]},"PublicApiTikTokPageSnapshotDto":{"type":"object","properties":{"recordedAt":{"type":"string","nullable":true},"adsCount":{"type":"number","nullable":true},"organicCount":{"type":"number","nullable":true},"totalTikToks":{"type":"number","nullable":true},"dailyViews":{"type":"number","nullable":true},"dailyLikes":{"type":"number","nullable":true},"dailyFollowers":{"type":"number","nullable":true}},"required":["recordedAt","adsCount","organicCount","totalTikToks","dailyViews","dailyLikes","dailyFollowers"]},"PublicApiTikTokLibraryItemDto":{"type":"object","properties":{"id":{"type":"string","example":"tiktok_7078586231734521093"},"tiktokId":{"type":"string","nullable":true},"type":{"type":"string","enum":["ad","organic"],"example":"ad"},"status":{"type":"string","enum":["active","inactive","unknown"],"example":"active"},"isPinned":{"type":"boolean","nullable":true},"publishedAt":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true},"updatedAt":{"type":"string","nullable":true},"daysRunning":{"type":"number","nullable":true},"media":{"$ref":"#/components/schemas/PublicApiTikTokMediaDto"},"content":{"$ref":"#/components/schemas/PublicApiTikTokContentDto"},"metrics":{"$ref":"#/components/schemas/PublicApiTikTokMetricsDto"},"profile":{"$ref":"#/components/schemas/PublicApiTikTokProfileDto"},"shop":{"$ref":"#/components/schemas/PublicApiTikTokShopDto"},"pin":{"$ref":"#/components/schemas/PublicApiTikTokPinDto"},"pageSnapshot":{"$ref":"#/components/schemas/PublicApiTikTokPageSnapshotDto"},"indexedAt":{"type":"string","nullable":true}},"required":["id","tiktokId","type","status","isPinned","publishedAt","createdAt","updatedAt","daysRunning","media","content","metrics","profile","shop","pin","pageSnapshot","indexedAt"]},"PublicApiTikTokLibraryPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25},"total":{"type":"number","nullable":true,"example":250},"totalPages":{"type":"number","nullable":true,"example":10}},"required":["page","limit","total","totalPages"]},"PublicApiTikTokLibraryResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"req_123"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiTikTokLibraryItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiTikTokLibraryPaginationDto"}},"required":["requestId","data","pagination"]},"QueryPublicApiTikTokLibraryRequestDto":{"type":"object","properties":{"search":{"example":["protein gummies","collagen"],"type":"array","items":{"type":"string"}},"keywordMode":{"type":"string","enum":["any","all"],"default":"any"},"searchArea":{"type":"string","enum":["all","caption","profile","hashtag","music"],"default":"all"},"type":{"type":"string","enum":["all","ad","organic"],"default":"all"},"status":{"type":"string","enum":["all","active","inactive"],"default":"all"},"mediaTypes":{"type":"array","items":{"type":"string","enum":["image","video","carousel"]}},"languages":{"example":["en","fr"],"description":"ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.","type":"array","items":{"type":"string"}},"countries":{"example":["US","FR"],"type":"array","items":{"type":"string"}},"categories":{"example":["Beauty Care","Outfit"],"description":"TikTok content categories, case-insensitive.","type":"array","items":{"type":"string"}},"hashtags":{"type":"array","items":{"type":"string"}},"tiktokPageIds":{"type":"array","items":{"type":"string"}},"tiktokPageId":{"type":"string"},"websiteId":{"type":"string"},"domain":{"type":"string"},"handle":{"type":"string"},"hasShopLinked":{"type":"string","enum":["yes","no"]},"publishedAfter":{"type":"string"},"publishedBefore":{"type":"string"},"updatedAfter":{"type":"string"},"updatedBefore":{"type":"string"},"minDaysRunning":{"type":"number"},"maxDaysRunning":{"type":"number"},"minViews":{"type":"number"},"maxViews":{"type":"number"},"minLikes":{"type":"number"},"minShares":{"type":"number"},"minEngagementRate":{"type":"number"},"maxEngagementRate":{"type":"number"},"minFollowers":{"type":"number"},"minProfileViews":{"type":"number"},"isPinned":{"type":"boolean"},"sortBy":{"type":"string","enum":["relevance","newest","updatedAt","views","likes","comments","shares","saves","engagementRate","daysRunning","followers"],"default":"newest"},"order":{"type":"string","enum":["asc","desc"],"default":"desc"},"page":{"type":"object","default":1,"minimum":1},"limit":{"type":"object","default":25,"minimum":1,"maximum":50}}},"PublicApiTikTokLinksDto":{"type":"object","properties":{"tiktokUrl":{"type":"string","nullable":true},"profileUrl":{"type":"string","nullable":true}},"required":["tiktokUrl","profileUrl"]},"PublicApiTikTokSourceDto":{"type":"object","properties":{"network":{"type":"string","nullable":true},"sourceType":{"type":"string","nullable":true},"tiktokPageId":{"type":"string","nullable":true},"websiteId":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true}},"required":["network","sourceType","tiktokPageId","websiteId","domain"]},"PublicApiTikTokLibraryItemDetailDto":{"type":"object","properties":{"id":{"type":"string","example":"tiktok_7078586231734521093"},"tiktokId":{"type":"string","nullable":true},"type":{"type":"string","enum":["ad","organic"],"example":"ad"},"status":{"type":"string","enum":["active","inactive","unknown"],"example":"active"},"isPinned":{"type":"boolean","nullable":true},"publishedAt":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true},"updatedAt":{"type":"string","nullable":true},"daysRunning":{"type":"number","nullable":true},"media":{"$ref":"#/components/schemas/PublicApiTikTokMediaDto"},"content":{"$ref":"#/components/schemas/PublicApiTikTokContentDto"},"metrics":{"$ref":"#/components/schemas/PublicApiTikTokMetricsDto"},"profile":{"$ref":"#/components/schemas/PublicApiTikTokProfileDto"},"shop":{"$ref":"#/components/schemas/PublicApiTikTokShopDto"},"pin":{"$ref":"#/components/schemas/PublicApiTikTokPinDto"},"pageSnapshot":{"$ref":"#/components/schemas/PublicApiTikTokPageSnapshotDto"},"indexedAt":{"type":"string","nullable":true},"links":{"$ref":"#/components/schemas/PublicApiTikTokLinksDto"},"source":{"$ref":"#/components/schemas/PublicApiTikTokSourceDto"}},"required":["id","tiktokId","type","status","isPinned","publishedAt","createdAt","updatedAt","daysRunning","media","content","metrics","profile","shop","pin","pageSnapshot","indexedAt","links","source"]},"PublicApiTikTokLibraryDetailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"req_123"},"data":{"$ref":"#/components/schemas/PublicApiTikTokLibraryItemDetailDto"}},"required":["requestId","data"]},"PublicApiEmailSearchType":{"type":"string","enum":["domain","email","shopKeywords"],"description":"Search mode for this request. Allowed values: `domain`, `email`, `shopKeywords`."},"PublicApiEmailKeywordMode":{"type":"string","enum":["any","all"],"description":"How multiple search keywords are combined. Allowed values: `any`, `all`."},"PublicApiEmailSortBy":{"type":"string","enum":["newest","oldest","relevance","monthlyVisits","bodyLength","shopEmailFrequency","event","promotionType"],"description":"Sort key for this request. Allowed values: `newest`, `oldest`, `relevance`, `monthlyVisits`, `bodyLength`, `shopEmailFrequency`, `event`, `promotionType`. These are discovery/indexing sorts, not opens/clicks/conversions performance rankings."},"PublicApiEmailSortOrder":{"type":"string","enum":["asc","desc"],"description":"Sort direction for this request. Allowed values: `asc`, `desc`."},"PublicApiEmailShopifyPlanFilter":{"type":"string","enum":["all","plus","nonPlus"],"description":"Enum value accepted by this request. Allowed values: `all`, `plus`, `nonPlus`."},"QueryPublicApiEmailsRequestDto":{"type":"object","properties":{"search":{"example":["welcome flow","discount"],"type":"array","items":{"type":"string"}},"searchType":{"example":"email","allOf":[{"$ref":"#/components/schemas/PublicApiEmailSearchType"}],"description":"Search mode for this request. Allowed values: `domain`, `email`, `shopKeywords`."},"keywordMode":{"example":"any","allOf":[{"$ref":"#/components/schemas/PublicApiEmailKeywordMode"}],"description":"How multiple search keywords are combined. Allowed values: `any`, `all`."},"sortBy":{"example":"newest","allOf":[{"$ref":"#/components/schemas/PublicApiEmailSortBy"}],"description":"Sort key for this request. Allowed values: `newest`, `oldest`, `relevance`, `monthlyVisits`, `bodyLength`, `shopEmailFrequency`, `event`, `promotionType`. These are discovery/indexing sorts, not opens/clicks/conversions performance rankings."},"order":{"example":"desc","allOf":[{"$ref":"#/components/schemas/PublicApiEmailSortOrder"}],"description":"Sort direction for this request. Allowed values: `asc`, `desc`."},"page":{"type":"number","example":1,"minimum":1},"limit":{"type":"number","example":50,"minimum":1,"maximum":100},"sentAfter":{"type":"string","example":"2026-01-01T00:00:00.000Z","format":"date-time"},"sentBefore":{"type":"string","example":"2026-01-31T23:59:59.999Z","format":"date-time"},"campaignTypes":{"example":["Newsletter","Welcome"],"type":"array","items":{"type":"string"}},"languages":{"example":["english","french"],"type":"array","items":{"type":"string"}},"promotionTypes":{"example":["Discount %","Free Delivery"],"description":"Stored promotion type names, matched case-insensitively (`Discount %`, `Discount % With Threshold`, `Free Delivery`, `BOGO`, `Bundle Deal`, `No Promotion`, …).","type":"array","items":{"type":"string"}},"promotionTypeIds":{"example":[4,7],"type":"array","items":{"type":"number"}},"categories":{"example":["Promotional Campaign"],"description":"Stored email category names, matched case-insensitively (`Promotional Campaign`, `Product Campaign`, `Launch Campaign`, `Relational Campaign`, `Event Campaign`, `Win-back Campaign`, `Survey`).","type":"array","items":{"type":"string"}},"emailCategoryIds":{"example":[4,1],"type":"array","items":{"type":"number"}},"eventNames":{"example":["Black Friday"],"type":"array","items":{"type":"string"}},"eventIds":{"example":[2,9],"type":"array","items":{"type":"number"}},"eventCategories":{"example":["Seasonal"],"type":"array","items":{"type":"string"}},"minBodyLength":{"type":"number","example":200,"minimum":0},"maxBodyLength":{"type":"number","example":1500,"minimum":0},"shopIds":{"example":["3f8aa146-6f96-46e8-9781-64db5166f9a8"],"type":"array","items":{"type":"string"},"description":"Stable public shop identifiers."},"minMonthlyVisits":{"type":"number","example":10000,"minimum":0},"maxMonthlyVisits":{"type":"number","example":500000,"minimum":0},"trafficGrowth":{"type":"string","example":"last30d=50=greater;AND;last90d=20=lower","description":"Traffic growth filter DSL using public rolling windows. Valid periods: `last30d`, `last90d`, `last180d`."},"minProductsCount":{"type":"number","example":10,"minimum":0},"maxProductsCount":{"type":"number","example":500,"minimum":0},"creationCountries":{"example":["US","FR"],"type":"array","items":{"type":"string"}},"excludeCreationCountries":{"example":["CN"],"type":"array","items":{"type":"string"}},"currencies":{"example":["USD","EUR"],"type":"array","items":{"type":"string"}},"shopDefaultLanguages":{"example":["en","fr"],"type":"array","items":{"type":"string"}},"mainMarketCountries":{"example":["US"],"type":"array","items":{"type":"string"}},"amongMarketCountries":{"example":["CA","GB"],"type":"array","items":{"type":"string"}},"excludeMarketCountries":{"example":["RU"],"type":"array","items":{"type":"string"}},"visitorCountries":{"example":["US","GB"],"description":"Alias of amongMarketCountries: matches shops with any of these countries among their markets. No separate visitor-country data is indexed.","type":"array","items":{"type":"string"}},"shopCreatedAfter":{"type":"string","example":"2024-01-01","format":"date"},"shopCreatedBefore":{"type":"string","example":"2024-12-31","format":"date"},"technologies":{"example":["shopify","woocommerce"],"description":"Main e-commerce platform slugs or ids (shopify, woocommerce, wordpress, magento, wix, …). Only the shop's main platform is indexed for emails; other technologies are rejected with unsupported_filter.","type":"array","items":{"type":"string"}},"shopifyPlan":{"example":"plus","allOf":[{"$ref":"#/components/schemas/PublicApiEmailShopifyPlanFilter"}],"description":"Enum value accepted by this request. Allowed values: `all`, `plus`, `nonPlus`."},"categoryIds":{"example":[166,204],"type":"array","items":{"type":"number"}},"minShopEmails90d":{"type":"number","example":10,"minimum":0},"maxShopEmails90d":{"type":"number","example":80,"minimum":0},"minAvgEmailsPerWeek":{"type":"number","example":1.5,"minimum":0},"maxAvgEmailsPerWeek":{"type":"number","example":5.2,"minimum":0},"minActiveAds":{"type":"number","example":5,"minimum":0},"maxActiveAds":{"type":"number","example":150,"minimum":0},"adsGrowth":{"type":"string","example":"last7d=40=greater","description":"Ads growth filter DSL using public rolling windows. Valid periods: `last7d`, `last30d`, `last90d`."},"minTrustpilotRating":{"type":"number","example":3.5,"minimum":0,"maximum":5},"maxTrustpilotRating":{"type":"number","example":5,"minimum":0,"maximum":5},"minTrustpilotReviewCount":{"type":"number","example":100,"minimum":0},"maxTrustpilotReviewCount":{"type":"number","example":5000,"minimum":0}}},"PublicApiEmailClassificationEventDto":{"type":"object","properties":{"name":{"type":"string","example":"Black Friday","nullable":true},"id":{"type":"number","example":1,"nullable":true},"category":{"type":"string","example":"Commercial Events","nullable":true}},"required":["name","id","category"]},"PublicApiEmailClassificationDto":{"type":"object","properties":{"promotionType":{"type":"string","example":"Discount %","nullable":true},"promotionTypeId":{"type":"number","example":1,"nullable":true},"category":{"type":"string","example":"Promotional Campaign","nullable":true},"categoryId":{"type":"number","example":4,"nullable":true},"event":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiEmailClassificationEventDto"}]}},"required":["promotionType","promotionTypeId","category","categoryId","event"]},"PublicApiEmailContentSummaryDto":{"type":"object","properties":{"subject":{"type":"string","example":"Up to 30% off this weekend"},"preheader":{"type":"string","example":"Limited-time offers picked for you.","nullable":true},"bodyPreview":{"type":"string","example":"Shop limited-time offers picked for you before they are gone.","nullable":true},"bodyLength":{"type":"number","example":428,"nullable":true},"screenshotUrl":{"type":"string","example":"https://cdn.example.com/emails/123.png","nullable":true}},"required":["subject","preheader","bodyPreview","bodyLength","screenshotUrl"]},"PublicApiEmailShopIdentityDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","nullable":true},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","example":"Example Shop","nullable":true}},"required":["id","domain","name"]},"PublicApiEmailSummaryDto":{"type":"object","properties":{"id":{"type":"number","example":123456},"sentAt":{"type":"string","example":"2026-04-18T12:30:00.000Z","format":"date-time"},"campaignType":{"type":"string","example":"Newsletter","nullable":true},"classification":{"$ref":"#/components/schemas/PublicApiEmailClassificationDto"},"content":{"$ref":"#/components/schemas/PublicApiEmailContentSummaryDto"},"shop":{"$ref":"#/components/schemas/PublicApiEmailShopIdentityDto"}},"required":["id","sentAt","campaignType","classification","content","shop"]},"PublicApiEmailsPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25},"total":{"type":"number","example":235,"nullable":true},"totalPages":{"type":"number","example":10,"nullable":true}},"required":["page","limit","total","totalPages"]},"PublicApiGetEmailsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiEmailSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiEmailsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiEmailHtmlDto":{"type":"object","properties":{"emailId":{"type":"number","example":123456,"description":"Stable public email identifier."},"html":{"type":"object","example":"<!doctype html><html><body>...</body></html>","nullable":true,"description":"Raw captured HTML for the email, when available."},"htmlLength":{"type":"number","example":12345,"description":"Length of the raw HTML string in characters. Zero when HTML is unavailable."}},"required":["emailId","html","htmlLength"]},"PublicApiGetEmailHtmlResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiEmailHtmlDto"}},"required":["requestId","data"]},"PublicApiEmailContentDetailDto":{"type":"object","properties":{"subject":{"type":"string","example":"Up to 30% off this weekend"},"preheader":{"type":"string","example":"Limited-time offers picked for you.","nullable":true},"bodyPreview":{"type":"string","example":"Shop limited-time offers picked for you before they are gone.","nullable":true},"bodyLength":{"type":"number","example":428,"nullable":true},"screenshotUrl":{"type":"string","example":"https://cdn.example.com/emails/123.png","nullable":true},"body":{"type":"string","example":"Shop the full collection with exclusive offers for this weekend only.","nullable":true}},"required":["subject","preheader","bodyPreview","bodyLength","screenshotUrl","body"]},"PublicApiEmailShopProfileDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US","nullable":true},"currency":{"type":"string","example":"USD","nullable":true},"defaultLanguage":{"type":"string","example":"en","nullable":true},"mainMarket":{"type":"string","example":"US","nullable":true},"isShopifyPlus":{"type":"boolean","example":true,"nullable":true},"visitorCountries":{"example":["US","CA","GB","FR","DE"],"nullable":true,"type":"array","items":{"type":"string"},"description":"ISO country codes of the top visitor countries, ordered by share of traffic."}},"required":["countryCode","currency","defaultLanguage","mainMarket","isShopifyPlus","visitorCountries"]},"PublicApiEmailShopTrafficDto":{"type":"object","properties":{"monthlyVisits":{"type":"number","example":45231,"nullable":true},"growth30d":{"type":"number","example":0.18,"nullable":true},"growth90d":{"type":"number","example":0.27,"nullable":true},"growth180d":{"type":"number","example":0.41,"nullable":true}},"required":["monthlyVisits","growth30d","growth90d","growth180d"]},"PublicApiEmailShopCatalogDto":{"type":"object","properties":{"productsCount":{"type":"number","example":124,"nullable":true},"categoryIds":{"example":[166,204],"nullable":true,"type":"array","items":{"type":"number"}}},"required":["productsCount","categoryIds"]},"PublicApiEmailShopMarketingDto":{"type":"object","properties":{"emailsLast90d":{"type":"number","example":37,"nullable":true},"avgEmailsPerWeek":{"type":"number","example":2.8,"nullable":true},"activeAds":{"type":"number","example":14,"nullable":true},"avgActiveAds7d":{"type":"number","example":9.2,"nullable":true},"avgActiveAds30d":{"type":"number","example":11.6,"nullable":true},"activeAdsGrowth7d":{"type":"number","example":0.12,"nullable":true,"description":"Active ads growth over the last 7 days (decimal, e.g. 0.12 = +12%)."},"activeAdsGrowth30d":{"type":"number","example":0.34,"nullable":true,"description":"Active ads growth over the last 30 days (decimal, e.g. 0.34 = +34%)."},"activeAdsGrowth90d":{"type":"number","example":0.58,"nullable":true,"description":"Active ads growth over the last 90 days (decimal, e.g. 0.58 = +58%)."}},"required":["emailsLast90d","avgEmailsPerWeek","activeAds","avgActiveAds7d","avgActiveAds30d","activeAdsGrowth7d","activeAdsGrowth30d","activeAdsGrowth90d"]},"PublicApiEmailShopTechnologyDto":{"type":"object","properties":{"mainTechnologyId":{"type":"string","format":"uuid","example":"04504d0b-df46-4f62-98b6-d4d9e14a2282","nullable":true,"description":"Id of the shop's main e-commerce platform."},"mainTechnologySlug":{"type":"string","example":"shopify","nullable":true},"mainTechnologyName":{"type":"string","example":"Shopify","nullable":true}},"required":["mainTechnologyId","mainTechnologySlug","mainTechnologyName"]},"PublicApiEmailShopTrustpilotDto":{"type":"object","properties":{"rating":{"type":"number","example":4.6,"nullable":true},"reviewCount":{"type":"number","example":1834,"nullable":true}},"required":["rating","reviewCount"]},"PublicApiEmailShopAnalyticsDto":{"type":"object","properties":{"campaignTypes":{"type":"object","additionalProperties":{"type":"number"},"nullable":true,"example":{"Marketing":75,"Newsletter":25},"description":"Share of the shop's emails over the last 90 days per campaign type, in percent (values sum to about 100)."},"categoryTypes":{"type":"object","additionalProperties":{"type":"number"},"nullable":true,"example":{"Promotional Campaign":28,"Product Campaign":2},"description":"Number of the shop's emails over the last 90 days per email category."},"emailsByDayOfWeek":{"type":"object","additionalProperties":{"type":"number"},"nullable":true,"example":{"0":3,"1":2,"3":5,"6":8},"description":"Emails sent by day of week using 0=Sunday ... 6=Saturday."}},"required":["campaignTypes","categoryTypes","emailsByDayOfWeek"]},"PublicApiEmailDetailShopDto":{"type":"object","properties":{"id":{"type":"string","example":"3f8aa146-6f96-46e8-9781-64db5166f9a8","nullable":true},"domain":{"type":"string","example":"example.com"},"name":{"type":"string","example":"Example Shop","nullable":true},"createdAt":{"type":"string","example":"2024-01-15T00:00:00.000Z","nullable":true,"format":"date-time"},"profile":{"$ref":"#/components/schemas/PublicApiEmailShopProfileDto"},"traffic":{"$ref":"#/components/schemas/PublicApiEmailShopTrafficDto"},"catalog":{"$ref":"#/components/schemas/PublicApiEmailShopCatalogDto"},"marketing":{"$ref":"#/components/schemas/PublicApiEmailShopMarketingDto"},"technology":{"$ref":"#/components/schemas/PublicApiEmailShopTechnologyDto"},"trustpilot":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiEmailShopTrustpilotDto"}]},"analytics":{"$ref":"#/components/schemas/PublicApiEmailShopAnalyticsDto"}},"required":["id","domain","name","createdAt","profile","traffic","catalog","marketing","technology","trustpilot","analytics"]},"PublicApiEmailDetailDto":{"type":"object","properties":{"id":{"type":"number","example":123456},"sentAt":{"type":"string","example":"2026-04-18T12:30:00.000Z","format":"date-time"},"campaignType":{"type":"string","example":"Newsletter","nullable":true},"classification":{"$ref":"#/components/schemas/PublicApiEmailClassificationDto"},"content":{"$ref":"#/components/schemas/PublicApiEmailContentDetailDto"},"shop":{"$ref":"#/components/schemas/PublicApiEmailDetailShopDto"},"language":{"type":"string","example":"english","nullable":true}},"required":["id","sentAt","campaignType","classification","content","shop","language"]},"PublicApiGetEmailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiEmailDetailDto"}},"required":["requestId","data"]},"PublicApiShopEmailsSortBy":{"type":"string","enum":["newest","oldest","relevance","event","promotionType"]},"PublicApiShopEmailLast90DaysStatsDto":{"type":"object","properties":{"totalEmails":{"type":"number","example":37,"description":"Total emails sent by this shop in the trailing 90 days."},"avgEmailsPerWeek":{"type":"number","example":2.8,"description":"Average emails sent per week over the trailing 90 days."},"emailsByDayOfWeek":{"type":"object","additionalProperties":{"type":"number"},"example":{"1":4,"3":7},"description":"Emails sent by day of week using 0=Sunday ... 6=Saturday."}},"required":["totalEmails","avgEmailsPerWeek","emailsByDayOfWeek"]},"PublicApiShopEmailCalendarStatsDto":{"type":"object","properties":{"month":{"type":"string","example":"2026-04","description":"Calendar month represented by this aggregate."},"totalEmails":{"type":"number","example":12,"description":"Total emails sent in the requested calendar month."},"emailsByDate":{"type":"object","additionalProperties":{"type":"number"},"example":{"2026-04-03":2,"2026-04-18":1},"description":"Sparse UTC calendar counts keyed by YYYY-MM-DD. Dates with zero emails are omitted."}},"required":["month","totalEmails","emailsByDate"]},"PublicApiShopEmailStatsDto":{"type":"object","properties":{"last90Days":{"$ref":"#/components/schemas/PublicApiShopEmailLast90DaysStatsDto"},"calendar":{"$ref":"#/components/schemas/PublicApiShopEmailCalendarStatsDto"}},"required":["last90Days","calendar"]},"PublicApiGetShopEmailStatsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiShopEmailStatsDto"}},"required":["requestId","data"]},"CreatePublicApiBrandtrackerBodyDto":{"type":"object","properties":{"facebookPageId":{"type":"string","example":"61554990830184","description":"Meta/Facebook page identifier to track. Exactly one of facebookPageId, websiteId, shopId, or domain is required."},"websiteId":{"type":"string","format":"uuid","description":"Website/shop identifier to track as a shop-level brandtracker. Exactly one target identifier is accepted.","example":"3d6fd2f0-5b34-4ffc-91ff-f59775544e5f"},"shopId":{"type":"string","format":"uuid","description":"Alias of websiteId for shop-oriented clients. Exactly one target identifier is accepted.","example":"3d6fd2f0-5b34-4ffc-91ff-f59775544e5f"},"domain":{"type":"string","example":"examplebrand.com","description":"Shop domain to resolve to exactly one known website and track as a shop-level brandtracker. Protocols, paths, and a leading www. are normalized away."},"folderId":{"type":"number","nullable":true,"example":42,"description":"Workspace brandtracker folder id. Null or omitted attaches the brandtracker at root."}}},"PublicApiBrandtrackerStatusDto":{"type":"object","properties":{"isLoaded":{"type":"boolean","example":true},"lastCrawledAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-20T10:00:00.000Z"}},"required":["isLoaded","lastCrawledAt"]},"PublicApiBrandtrackerFolderDto":{"type":"object","properties":{"id":{"type":"number","example":42},"name":{"type":"string","example":"Competitors"}},"required":["id","name"]},"PublicApiBrandtrackerAdvertisingDto":{"type":"object","properties":{"activeAds":{"type":"number","example":18},"newAdsLastDay":{"type":"number","example":3},"newAdsLast7Days":{"type":"number","example":11},"newAdsLast30Days":{"type":"number","example":34}},"required":["activeAds","newAdsLastDay","newAdsLast7Days","newAdsLast30Days"]},"PublicApiBrandtrackerWebsiteSocialNetworksDto":{"type":"object","properties":{"facebook":{"type":"string","nullable":true,"example":"https://facebook.com/examplebrand"},"instagram":{"type":"string","nullable":true,"example":"https://instagram.com/examplebrand"},"youtube":{"type":"string","nullable":true,"example":"https://youtube.com/@examplebrand"}}},"PublicApiBrandtrackerWebsiteDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"3d6fd2f0-5b34-4ffc-91ff-f59775544e5f"},"domain":{"type":"string","example":"examplebrand.com"},"siteName":{"type":"string","nullable":true,"example":"Example Brand"},"trafficNumber":{"type":"number","nullable":true,"example":145230},"trafficChange":{"type":"number","nullable":true,"example":12.4},"monthlyTraffic":{"type":"object","nullable":true,"additionalProperties":{"type":"number"},"example":{"2026-01":102343,"2026-02":114230}},"socialNetworks":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerWebsiteSocialNetworksDto"}]}},"required":["id","domain","siteName","trafficNumber","trafficChange","monthlyTraffic","socialNetworks"]},"PublicApiBrandtrackerSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"name":{"type":"string","example":"Example Brand"},"facebookPageId":{"type":"string","example":"61554990830184"},"workspaceLinkId":{"type":"number","description":"Workspace link identifier. Present on mutation responses and useful for follow-up move/delete operations.","example":99},"targetType":{"type":"string","enum":["shop","page"],"description":"Resolved tracked target type. Present on mutation responses.","example":"shop"},"websiteId":{"type":"string","nullable":true,"format":"uuid","description":"Resolved website/shop identifier when the brandtracker target is shop-level.","example":"3d6fd2f0-5b34-4ffc-91ff-f59775544e5f"},"domain":{"type":"string","nullable":true,"description":"Resolved canonical domain when the brandtracker target is shop-level.","example":"examplebrand.com"},"avatarUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/profile_picture/61554990830184.jpg"},"status":{"$ref":"#/components/schemas/PublicApiBrandtrackerStatusDto"},"workspaceAddedAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-15T09:00:00.000Z"},"folder":{"nullable":true,"description":"Primary folder membership, ordered by folder rank, name, then id. Null when the tracked brand has no folder memberships.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerFolderDto"}]},"advertising":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdvertisingDto"},"websites":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerWebsiteDto"}},"totalTraffic":{"type":"number","example":145230}},"required":["id","name","facebookPageId","avatarUrl","status","workspaceAddedAt","folder","advertising","websites","totalTraffic"]},"PublicApiCreateBrandtrackerResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerSummaryDto"},"created":{"type":"boolean","description":"True when this call created or reactivated a workspace brandtracker; false when an active link already existed.","example":true}},"required":["requestId","data","created"]},"PublicApiBrandtrackerQuotaExhaustedDetailsDto":{"type":"object","properties":{"feature":{"type":"string","example":"brandtracker_v3"},"limit":{"type":"number","example":10,"description":"Tracked-brand slots of the plan, add-ons included."},"used":{"type":"number","example":10,"description":"Slots taken: active tracked brands plus slots held by a cooldown."},"reservedByCooldown":{"type":"number","example":2,"description":"Slots still held for 24h after a tracked brand was removed."},"nextSlotAvailableAt":{"type":"string","format":"date-time","nullable":true,"example":"2026-09-26T09:30:00.000Z","description":"When a cooldown ending frees a slot; null when only removing a brand (its slot frees 24h later) or upgrading helps."},"currentUsage":{"type":"number","example":10,"deprecated":true,"description":"Same as `used`."},"maxLimit":{"type":"number","example":10,"deprecated":true,"description":"Same as `limit`."}},"required":["feature","limit","used","reservedByCooldown","nextSlotAvailableAt","currentUsage","maxLimit"]},"PublicApiBrandtrackerQuotaExhaustedErrorDto":{"type":"object","properties":{"code":{"type":"string","enum":["quota_exhausted"],"example":"quota_exhausted"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"$ref":"#/components/schemas/PublicApiBrandtrackerQuotaExhaustedDetailsDto"}},"required":["code","message","requestId","details"]},"PublicApiBrandtrackerQuotaExhaustedResponseDto":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/PublicApiBrandtrackerQuotaExhaustedErrorDto"}},"required":["error"]},"CreatePublicApiBrandtrackerFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","example":"Competitors","description":"Workspace-scoped folder name. Rank is assigned atomically as the next workspace rank."}},"required":["name"]},"PublicApiBrandtrackerFolderMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiWorkspaceFolderDto"}},"required":["requestId","data"]},"RenamePublicApiBrandtrackerFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","example":"Priority Competitors","description":"New workspace-scoped folder name."}},"required":["name"]},"DeletePublicApiBrandtrackerFolderBodyDto":{"type":"object","properties":{"action":{"type":"string","enum":["move-to-default","delete-brandtrackers"],"description":"move-to-default keeps affected trackers active and clears their folder. delete-brandtrackers deactivates affected active workspace links, consumes one persistent create/delete quota unit for the whole folder delete, and decrements active brandtracker usage by affectedCount.","example":"move-to-default"},"confirm":{"type":"boolean","example":true,"description":"Must be true for destructive folder delete requests."}},"required":["action","confirm"]},"PublicApiDeleteBrandtrackerFolderDataDto":{"type":"object","properties":{"deleted":{"type":"boolean","example":true},"action":{"type":"string","enum":["move-to-default","delete-brandtrackers"]},"affectedCount":{"type":"number","description":"Number of active workspace links moved to root or deactivated by the folder delete action.","example":12}},"required":["deleted","action","affectedCount"]},"PublicApiDeleteBrandtrackerFolderResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiDeleteBrandtrackerFolderDataDto"}},"required":["requestId","data"]},"MovePublicApiBrandtrackerWorkspaceLinksBodyDto":{"type":"object","properties":{"brandtrackerIds":{"type":"array","items":{"type":"string"},"description":"Public brandtracker ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required."},"workspaceLinkIds":{"type":"array","items":{"type":"number"},"description":"Workspace link ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required."},"folderId":{"type":"number","nullable":true,"example":42,"description":"Destination workspace folder id, or null to move to root."}},"required":["folderId"]},"PublicApiBrandtrackerWorkspaceLinksMutationDataDto":{"type":"object","properties":{"requestedCount":{"type":"number","description":"Deduplicated number of requested ids in the submitted address set.","example":3},"affectedCount":{"type":"number","description":"Number of active workspace links changed. Cross-workspace, inactive, or unknown ids are excluded and reported as not found where safe.","example":2},"notFoundBrandtrackerIds":{"type":"array","items":{"type":"string"},"description":"Requested public brandtracker ids that did not resolve to active links in this workspace."},"notFoundWorkspaceLinkIds":{"type":"array","items":{"type":"number"},"description":"Requested workspace link ids that did not resolve to active links in this workspace."},"cooldownUntil":{"type":"string","format":"date-time","example":"2026-09-26T09:30:00.000Z","description":"Removals only: the removed brands keep their slots until this time (24h cooldown)."}},"required":["requestedCount","affectedCount"]},"PublicApiBrandtrackerWorkspaceLinksMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerWorkspaceLinksMutationDataDto"}},"required":["requestId","data"]},"DeletePublicApiBrandtrackerWorkspaceLinksBodyDto":{"type":"object","properties":{"brandtrackerIds":{"type":"array","items":{"type":"string"},"description":"Public brandtracker ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required."},"workspaceLinkIds":{"type":"array","items":{"type":"number"},"description":"Workspace link ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required."},"confirm":{"type":"boolean","example":true,"description":"Must be true for destructive bulk delete requests."}},"required":["confirm"]},"PublicApiDeleteBrandtrackerDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"deleted":{"type":"boolean","example":true},"cooldownUntil":{"type":"string","format":"date-time","example":"2026-09-26T09:30:00.000Z","description":"The removed brand keeps its tracked-brand slot until this time (24h cooldown); the slot still counts against the plan limit, and re-adding the same brand before then reuses it."}},"required":["id","deleted","cooldownUntil"]},"PublicApiDeleteBrandtrackerResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiDeleteBrandtrackerDataDto"}},"required":["requestId","data"]},"PublicApiBrandtrackersSortBy":{"type":"string","enum":["newAdsLastDay","newAdsLast7Days","newAdsLast30Days","activeAds","totalTraffic","name","createdAt"]},"PublicApiBrandtrackersPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25},"total":{"type":"number","example":128},"totalPages":{"type":"number","example":6}},"required":["page","limit","total","totalPages"]},"PublicApiGetBrandtrackersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackersPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerPageProfileDto":{"type":"object","properties":{"about":{"type":"string","nullable":true,"example":"Global fashion brand"},"category":{"type":"string","nullable":true,"example":"Clothing (Brand)"},"facebookLikes":{"type":"number","nullable":true,"example":523400},"instagramFollowers":{"type":"number","nullable":true,"example":841200},"instagramUsername":{"type":"string","nullable":true,"example":"examplebrand"},"profileUri":{"type":"string","nullable":true,"example":"https://www.facebook.com/examplebrand"},"runningAds":{"type":"number","nullable":true,"example":18}},"required":["about","category","facebookLikes","instagramFollowers","instagramUsername","profileUri","runningAds"]},"PublicApiBrandtrackerLiveAdCountDto":{"type":"object","properties":{"activeCount":{"type":"number","nullable":true,"example":18},"inactiveCount":{"type":"number","nullable":true,"example":4}},"required":["activeCount","inactiveCount"]},"PublicApiBrandtrackerStatisticsDto":{"type":"object","properties":{"urlCount":{"type":"object","additionalProperties":{"type":"number"},"example":{"https://examplebrand.com/products/hero":14}},"ctaCount":{"type":"object","additionalProperties":{"type":"number"},"example":{"SHOP_NOW":10,"LEARN_MORE":4}},"liveAdCount":{"$ref":"#/components/schemas/PublicApiBrandtrackerLiveAdCountDto"},"formatCount":{"type":"object","additionalProperties":{"type":"number"},"example":{"IMAGE":8,"VIDEO":10}},"euData":{"type":"object","nullable":true,"additionalProperties":true,"example":null}},"required":["urlCount","ctaCount","liveAdCount","formatCount","euData"]},"PublicApiBrandtrackerDetailDto":{"type":"object","properties":{"id":{"type":"string","description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"},"name":{"type":"string","example":"Example Brand"},"facebookPageId":{"type":"string","example":"61554990830184"},"workspaceLinkId":{"type":"number","description":"Workspace link identifier. Present on mutation responses and useful for follow-up move/delete operations.","example":99},"targetType":{"type":"string","enum":["shop","page"],"description":"Resolved tracked target type. Present on mutation responses.","example":"shop"},"websiteId":{"type":"string","nullable":true,"format":"uuid","description":"Resolved website/shop identifier when the brandtracker target is shop-level.","example":"3d6fd2f0-5b34-4ffc-91ff-f59775544e5f"},"domain":{"type":"string","nullable":true,"description":"Resolved canonical domain when the brandtracker target is shop-level.","example":"examplebrand.com"},"avatarUrl":{"type":"string","nullable":true,"example":"https://medias.trendtrack.io/profile_picture/61554990830184.jpg"},"status":{"$ref":"#/components/schemas/PublicApiBrandtrackerStatusDto"},"workspaceAddedAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-15T09:00:00.000Z"},"folder":{"nullable":true,"description":"Primary folder membership, ordered by folder rank, name, then id. Null when the tracked brand has no folder memberships.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerFolderDto"}]},"advertising":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdvertisingDto"},"websites":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerWebsiteDto"}},"totalTraffic":{"type":"number","example":145230},"createdAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-01T12:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"format":"date-time","example":"2026-04-21T09:30:00.000Z"},"pageProfile":{"$ref":"#/components/schemas/PublicApiBrandtrackerPageProfileDto"},"statistics":{"$ref":"#/components/schemas/PublicApiBrandtrackerStatisticsDto"}},"required":["id","name","facebookPageId","avatarUrl","status","workspaceAddedAt","folder","advertising","websites","totalTraffic","createdAt","updatedAt","pageProfile","statistics"]},"PublicApiGetBrandtrackerDetailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerDetailDto"}},"required":["requestId","data"]},"PublicApiSnapshotStatusDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Snapshot date in YYYY-MM-DD format.","example":"2026-04-23"},"status":{"type":"string","enum":["ready","indexing","scheduled"],"description":"Readiness status. ready means the brandtracker's pages were collected that day, with every page aggregate; indexing and scheduled are reserved and not currently returned.","example":"ready"},"usableRows":{"type":"number","description":"Pages of this brandtracker collected on this snapshot date. Reach is only published for EU/UK ads and is not required.","example":1240},"indexedRows":{"type":"number","description":"Pages of this brandtracker collected on this snapshot date.","example":1300}},"required":["date","status","usableRows","indexedRows"]},"PublicApiBrandtrackerSnapshotsDto":{"type":"object","properties":{"latestDate":{"type":"string","nullable":true,"deprecated":true,"description":"Deprecated compatibility alias of latestReadyDate. Latest ready snapshot date for this brandtracker, or null when no ready snapshots exist.","example":"2026-04-20"},"latestReadyDate":{"type":"string","nullable":true,"description":"Latest collection day of this brandtracker's pages within the history the workspace may read, or null when none was collected. Reach (EU/UK ads only) does not affect it.","example":"2026-04-20"},"latestScheduledDate":{"type":"string","nullable":true,"description":"Latest collection day of this brandtracker's pages. Equal to latestReadyDate: a collected day is complete, so no day is indexed without being ready.","example":"2026-04-21"},"dates":{"type":"array","items":{"type":"string"},"description":"Available snapshot dates in descending order. Preserved for backwards compatibility; mirrors snapshots[].date.","example":["2026-04-20","2026-04-19"]},"snapshots":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSnapshotStatusDto"},"description":"Snapshot dates with readiness status and row counts in descending date order."}},"required":["latestDate","latestReadyDate","latestScheduledDate","dates","snapshots"]},"PublicApiBrandtrackerInsightsPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":20},"total":{"type":"number","example":128},"totalPages":{"type":"number","example":7}},"required":["page","limit","total","totalPages"]},"PublicApiGetBrandtrackerSnapshotsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerSnapshotsDto"},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerAdsSort":{"type":"string","enum":["newest","createdAt","longestRunning","reach","duplicates","adOrder","relevance"]},"PublicApiBrandtrackerAdsStatus":{"type":"string","enum":["all","active","inactive"]},"PublicApiBrandtrackerAdsMediaType":{"type":"string","enum":["all","image","video"]},"PublicApiBrandtrackerAdsKeywordMode":{"type":"string","enum":["any","all"]},"PublicApiBrandtrackerAdsSpendPeriod":{"type":"string","enum":["total","last24h","last7d","last30d"]},"PublicApiBrandtrackerAdsSex":{"type":"string","enum":["men","women","all"]},"PublicApiBrandtrackerAdsGrowthRank":{"type":"string","enum":["rising","falling","stable"]},"PublicApiGetBrandtrackerAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerPartnershipAdsCountDto":{"type":"object","properties":{"count":{"type":"number","minimum":0,"description":"Deduped public ad groups matching the partnership ads list filters."}},"required":["count"]},"PublicApiGetBrandtrackerPartnershipAdsCountResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Request identifier mirrored in the X-Request-Id response header.","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerPartnershipAdsCountDto"}},"required":["requestId","data"]},"PublicApiBrandtrackerInsightsTimePeriod":{"type":"string","enum":["live","last24h","last3d","last7d","last30d","last3m","last6m","last1y"]},"PublicApiBrandtrackerInsightsSortOrder":{"type":"string","enum":["asc","desc"]},"PublicApiBrandtrackerHooksSortBy":{"type":"string","enum":["usageCount","longestRunning","totalImpressions","firstUsedAt","lastUsedAt"]},"PublicApiBrandtrackerHookSampleAdDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789"},"mediaUrl":{"type":"string","example":"https://cdn.example.com/ads/creative.mp4","nullable":true},"thumbnailUrl":{"type":"string","example":"https://cdn.example.com/ads/creative-thumb.jpg","nullable":true},"fullText":{"type":"string","example":"This is the full transcript text for the sampled ad.","nullable":true}},"required":["adId","mediaUrl","thumbnailUrl","fullText"]},"PublicApiBrandtrackerHookDto":{"type":"object","properties":{"hook":{"type":"string","example":"Stop scrolling."},"usageCount":{"type":"number","example":12},"longestRunning":{"type":"number","example":47},"totalImpressions":{"type":"number","example":152340,"description":"Total impressions/reach contributed by ads using this hook. This aligns with Meta Ad Library reach vocabulary used elsewhere in the ads API."},"firstUsedAt":{"type":"string","example":"2026-02-01T09:12:00.000Z","nullable":true,"format":"date-time"},"lastUsedAt":{"type":"string","example":"2026-04-19T12:30:00.000Z","nullable":true,"format":"date-time"},"sampleAd":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerHookSampleAdDto"}]}},"required":["hook","usageCount","longestRunning","totalImpressions","firstUsedAt","lastUsedAt","sampleAd"]},"PublicApiGetBrandtrackerHooksResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerHookDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerTranscriptsSortBy":{"type":"string","enum":["usageCount","longestRunning","totalImpressions","firstUsedAt","lastUsedAt"]},"PublicApiBrandtrackerTranscriptSampleAdDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789"},"mediaUrl":{"type":"string","example":"https://cdn.example.com/ads/creative.mp4","nullable":true},"thumbnailUrl":{"type":"string","example":"https://cdn.example.com/ads/creative-thumb.jpg","nullable":true}},"required":["adId","mediaUrl","thumbnailUrl"]},"PublicApiBrandtrackerTranscriptDto":{"type":"object","properties":{"fullText":{"type":"string","example":"This is the full transcript text used by multiple ads in this brandtracker."},"usageCount":{"type":"number","example":12},"longestRunning":{"type":"number","example":47},"totalImpressions":{"type":"number","example":152340,"description":"Total impressions/reach contributed by ads using this transcript. This aligns with Meta Ad Library reach vocabulary used elsewhere in the ads API."},"firstUsedAt":{"type":"string","example":"2026-02-01T09:12:00.000Z","nullable":true,"format":"date-time"},"lastUsedAt":{"type":"string","example":"2026-04-19T12:30:00.000Z","nullable":true,"format":"date-time"},"sampleAd":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerTranscriptSampleAdDto"}]}},"required":["fullText","usageCount","longestRunning","totalImpressions","firstUsedAt","lastUsedAt","sampleAd"]},"PublicApiGetBrandtrackerTranscriptsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTranscriptDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerHeadlinesSortBy":{"type":"string","enum":["usageCount","longestRunning"]},"PublicApiBrandtrackerHeadlineDto":{"type":"object","properties":{"headline":{"type":"string","example":"Summer sale is live"},"usageCount":{"type":"number","example":18},"longestRunning":{"type":"number","example":52}},"required":["headline","usageCount","longestRunning"]},"PublicApiGetBrandtrackerHeadlinesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerHeadlineDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerAdCopiesSortBy":{"type":"string","enum":["usageCount","longestRunning"]},"PublicApiBrandtrackerAdCopyDto":{"type":"object","properties":{"adCopy":{"type":"string","example":"Get 30% off selected products this week only."},"usageCount":{"type":"number","example":21},"longestRunning":{"type":"number","example":43}},"required":["adCopy","usageCount","longestRunning"]},"PublicApiGetBrandtrackerAdCopiesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdCopyDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerLandingPagesSortBy":{"type":"string","enum":["usageCount","longestRunning","totalImpressions"]},"PublicApiBrandtrackerTechnologyDto":{"type":"object","properties":{"id":{"type":"string","example":"04504d0b-df46-4f62-98b6-d4d9e14a2282"},"name":{"type":"string","example":"Shopify"},"iconUrl":{"type":"string","example":"https://cdn.example.com/technology_icons/shopify.svg","nullable":true}},"required":["id","name","iconUrl"]},"PublicApiBrandtrackerLandingPageScreenshotsDto":{"type":"object","properties":{"desktop":{"type":"object","example":"https://cdn.example.com/screenshots/landing-page-full.png","nullable":true,"description":"Latest desktop/full-page screenshot URL when available."},"mobile":{"type":"object","example":"https://cdn.example.com/screenshots/landing-page-mobile.png","nullable":true,"description":"Latest mobile screenshot URL when available."},"head":{"type":"object","example":"https://cdn.example.com/screenshots/landing-page-head.png","nullable":true,"description":"Latest above-the-fold/head screenshot URL when available."}},"required":["desktop","mobile","head"]},"PublicApiBrandtrackerLandingPageDto":{"type":"object","properties":{"landingPage":{"type":"string","example":"https://example.com/products/summer-sale"},"usageCount":{"type":"number","example":16},"longestRunning":{"type":"number","example":41},"totalImpressions":{"type":"number","example":305400,"description":"Total impressions/reach contributed by ads pointing to this landing page. This aligns with Meta Ad Library reach vocabulary used elsewhere in the ads API."},"technologies":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTechnologyDto"}},"screenshots":{"description":"Best-effort landing page screenshot preview URLs from the screenshots table.","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageScreenshotsDto"}]}},"required":["landingPage","usageCount","longestRunning","totalImpressions","technologies","screenshots"]},"PublicApiGetBrandtrackerLandingPagesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerLandingPagesSimpleSortBy":{"type":"string","enum":["usageCount","activeAdsCount"]},"PublicApiBrandtrackerLandingPageSimpleDto":{"type":"object","properties":{"landingPage":{"type":"string","example":"https://example.com/products/summer-sale","description":"Representative landing page URL with query string, fragment, and trailing slash removed."},"normalizedLandingPage":{"type":"string","example":"example.com/products/summer-sale","description":"Normalized grouping key. Hostname is lowercased and leading www. is removed; query strings and fragments are ignored."},"usageCount":{"type":"number","example":16},"activeAdsCount":{"type":"number","example":5,"description":"Number of currently active ads in this group for rolling windows. For live and snapshot queries this matches usageCount."},"technologies":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTechnologyDto"}},"screenshots":{"description":"Best-effort landing page screenshot preview URLs from the screenshots table.","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageScreenshotsDto"}]}},"required":["landingPage","normalizedLandingPage","usageCount","activeAdsCount","technologies","screenshots"]},"PublicApiGetBrandtrackerLandingPagesSimpleResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageSimpleDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerCreativesSortBy":{"type":"string","enum":["firstSeenAt","daysRunning","duplicates"]},"PublicApiBrandtrackerCreativeMediaType":{"type":"string","enum":["all","image","video"]},"PublicApiBrandtrackerCreativeDto":{"type":"object","properties":{"adId":{"type":"string","example":"facebook_123456789"},"mediaType":{"type":"string","enum":["image","video","unknown"],"example":"video"},"mediaUrl":{"type":"string","example":"https://cdn.example.com/ads/creative.mp4","nullable":true},"thumbnailUrl":{"type":"string","example":"https://cdn.example.com/ads/creative-thumb.jpg","nullable":true},"firstSeenAt":{"type":"string","example":"2026-03-01T08:00:00.000Z","nullable":true,"format":"date-time"},"daysRunning":{"type":"number","example":27},"duplicates":{"type":"number","example":4,"nullable":true}},"required":["adId","mediaType","mediaUrl","thumbnailUrl","firstSeenAt","daysRunning","duplicates"]},"PublicApiGetBrandtrackerCreativesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerCreativeDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerPartnersSortBy":{"type":"string","enum":["activeAds","launchDate","reach","estimatedSpend"]},"PublicApiBrandtrackerPartnerDto":{"type":"object","properties":{"facebookPageId":{"type":"string","example":"61554990830184"},"name":{"type":"string","example":"Example Partner","nullable":true},"activeAds":{"type":"number","example":8},"launchDate":{"type":"string","example":"2026-02-18T13:40:00.000Z","nullable":true,"format":"date-time"},"reach":{"type":"number","example":245000,"description":"Partner ad reach. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"estimatedSpend":{"type":"number","example":2205}},"required":["facebookPageId","name","activeAds","launchDate","reach","estimatedSpend"]},"PublicApiGetBrandtrackerPartnersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerPartnerDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerMediaMixFormatCountDto":{"type":"object","properties":{"image":{"type":"number","example":12},"video":{"type":"number","example":8},"dco":{"type":"number","example":2},"other":{"type":"number","example":1}},"required":["image","video","dco","other"]},"PublicApiBrandtrackerMediaMixDto":{"type":"object","properties":{"activeAds":{"type":"number","example":23,"description":"Number of deduped eligible ads in the media mix. Equals image + video + dco + other."},"formatCount":{"description":"Media-format buckets counted from the same deduped eligible-ad set as activeAds. Carousel is not exposed as a separate media-mix bucket; carousel creatives are currently folded into image, video, dco, or other based on the indexed media format.","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerMediaMixFormatCountDto"}]}},"required":["activeAds","formatCount"]},"PublicApiFreshnessMetaDto":{"type":"object","properties":{"requestedSnapshotDate":{"type":"string","nullable":true,"example":"latest","description":"Snapshot date requested by the client. Null when snapshotDate was omitted."},"resolvedSnapshotDate":{"type":"string","nullable":true,"example":"2026-04-23","description":"Snapshot date actually used by the endpoint. Null when no ready snapshot was available or no snapshot resolution was needed."},"dataFreshnessLagDays":{"type":"number","nullable":true,"example":1,"description":"Difference in whole UTC days between today and the resolved snapshot date. Null when no snapshot was resolved."},"periodNote":{"type":"string","example":"period=today uses the latest ready completed snapshot date instead of partial current-day data.","description":"Optional note clarifying period-specific freshness behavior."}},"required":["requestedSnapshotDate","resolvedSnapshotDate","dataFreshnessLagDays"]},"PublicApiGetBrandtrackerMediaMixResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerMediaMixDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"}},"required":["requestId","data","meta"]},"PublicApiBrandtrackerCountryDistributionPointDto":{"type":"object","properties":{"countryCode":{"type":"string","example":"US"},"reach":{"type":"number","example":125000,"description":"Reach attributed to this country. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."}},"required":["countryCode","reach"]},"PublicApiBrandtrackerAgeDistributionPointDto":{"type":"object","properties":{"ageRange":{"type":"string","example":"25-34"},"reach":{"type":"number","example":82000,"description":"Reach attributed to this age range. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."}},"required":["ageRange","reach"]},"PublicApiBrandtrackerGenderDistributionPointDto":{"type":"object","properties":{"gender":{"type":"string","enum":["female","male","unknown"],"example":"female"},"reach":{"type":"number","example":91000,"description":"Reach attributed to this gender bucket. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."}},"required":["gender","reach"]},"PublicApiBrandtrackerDemographyDto":{"type":"object","properties":{"hasData":{"type":"boolean","example":true},"countryDistribution":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerCountryDistributionPointDto"}},"ageDistribution":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAgeDistributionPointDto"}},"genderDistribution":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerGenderDistributionPointDto"}}},"required":["hasData","countryDistribution","ageDistribution","genderDistribution"]},"PublicApiGetBrandtrackerDemographyResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerDemographyDto"}},"required":["requestId","data"]},"PublicApiBrandtrackerTopAdsSortBy":{"type":"string","enum":["currentRank","rankDelta","rankDelta7d","rankDelta14d","rankDelta30d","reach","reachDelta1d","reachDelta7d","reachDelta30d","daysRunning","duplicates"]},"PublicApiBrandtrackerTopAdsPeriod":{"type":"string","enum":["today","yesterday","last1d","last7d","last14d","last30d","total"]},"PublicApiBrandtrackerTopAdMetricsDto":{"type":"object","properties":{"totalReach":{"type":"number","example":152340,"description":"Total reach for the ranked ad. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric; EU impressions/reach are used where available."},"duplicateCount":{"type":"number","example":4},"daysRunning":{"type":"number","example":27},"currentRank":{"type":"number","example":3,"nullable":true}},"required":["totalReach","duplicateCount","daysRunning","currentRank"]},"PublicApiBrandtrackerTopAdDto":{"type":"object","properties":{"ad":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"},"metrics":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdMetricsDto"}},"required":["ad","metrics"]},"PublicApiTopAdsEmptyReason":{"type":"string","enum":["no_snapshot_for_period","no_reach_history_for_period","no_matching_ads"],"description":"Present on empty result sets to distinguish filters with no matching ads."},"PublicApiTopAdsMetaDto":{"type":"object","properties":{"reason":{"description":"Present on empty result sets to distinguish filters with no matching ads.","allOf":[{"$ref":"#/components/schemas/PublicApiTopAdsEmptyReason"}]}}},"PublicApiGetBrandtrackerTopAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"description":"Optional empty-result diagnostics. Omitted on normal top-ads responses.","allOf":[{"$ref":"#/components/schemas/PublicApiTopAdsMetaDto"}]}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerScalingAdsTimeWindow":{"type":"string","enum":["last7d","last14d","last30d","7d","14d","30d"]},"PublicApiBrandtrackerScalingAdsSortBy":{"type":"string","enum":["rankDelta","currentRank","rank_delta","current_rank"]},"PublicApiBrandtrackerScalingAdMetricsDto":{"type":"object","properties":{"currentRank":{"type":"number","example":4},"previousRank":{"type":"number","example":17},"rankDelta":{"type":"number","example":13,"description":"Positive rank improvement over the selected comparison window."},"improvementPct":{"type":"object","example":76.5,"nullable":true,"description":"Percentage improvement from previousRank to currentRank over the selected comparison window."}},"required":["currentRank","previousRank","rankDelta","improvementPct"]},"PublicApiBrandtrackerAdRankTrajectoryPointDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-20","description":"Trajectory point date in YYYY-MM-DD format."},"rank":{"type":"number","example":4},"totalAds":{"type":"object","example":250,"nullable":true,"description":"Estimated total ranked ads for this snapshot when available."}},"required":["date","rank","totalAds"]},"PublicApiBrandtrackerScalingAdDto":{"type":"object","properties":{"ad":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"},"metrics":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdMetricsDto"},"trajectory":{"description":"Daily rank trajectory for this ad over the selected comparison window.","type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdRankTrajectoryPointDto"}}},"required":["ad","metrics","trajectory"]},"PublicApiGetBrandtrackerScalingAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"}},"required":["requestId","data","pagination","meta"]},"PublicApiBrandtrackerTimeSeriesGranularity":{"type":"string","enum":["daily","weekly","monthly"]},"PublicApiBrandtrackerTimeSeriesPeriod":{"type":"string","enum":["today","yesterday","1d","7d","14d","30d","90d","365d"]},"PublicApiBrandtrackerTimeSeriesDateRangeDto":{"type":"object","properties":{"startDate":{"type":"string","example":"2026-01-01","format":"date"},"endDate":{"type":"string","example":"2026-04-20","format":"date"}},"required":["startDate","endDate"]},"PublicApiBrandtrackerCountTimeSeriesPointDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-20","format":"date"},"count":{"type":"number","example":12}},"required":["date","count"]},"PublicApiBrandtrackerEuImpressionsSpendTimeSeriesPointDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-20","format":"date"},"impressions":{"type":"number","example":12450,"description":"Impression delta within this bucket."},"cumulativeImpressions":{"type":"number","example":431200,"nullable":true,"description":"Latest cumulative EU impressions value observed in this bucket."},"estimatedSpend":{"type":"number","example":112.05,"description":"Estimated spend for this bucket, computed from impressions and cpm."}},"required":["date","impressions","cumulativeImpressions","estimatedSpend"]},"PublicApiBrandtrackerTimeSeriesDto":{"type":"object","properties":{"granularity":{"type":"string","enum":["daily","weekly","monthly"],"example":"daily"},"dateRange":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesDateRangeDto"},"adsLaunched":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerCountTimeSeriesPointDto"}},"liveAds":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerCountTimeSeriesPointDto"}},"euImpressionsSpend":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerEuImpressionsSpendTimeSeriesPointDto"},"description":"EU impressions/reach spend time series. For Meta Ad Library data, reach is the public-facing impressions-style vocabulary used by related ad DTOs."},"cpm":{"type":"number","example":9}},"required":["granularity","dateRange","adsLaunched","liveAds","euImpressionsSpend","cpm"]},"PublicApiBrandtrackerOverviewLandingPagesSectionDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["data","pagination"]},"PublicApiBrandtrackerOverviewTopAdsSectionDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["data","pagination"]},"PublicApiBrandtrackerOverviewAdsPreviewSectionDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdsPaginationDto"}},"required":["data","pagination"]},"PublicApiBrandtrackerOverviewDto":{"type":"object","properties":{"graph":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesDto"},"mediaMix":{"$ref":"#/components/schemas/PublicApiBrandtrackerMediaMixDto"},"topLandingPages":{"$ref":"#/components/schemas/PublicApiBrandtrackerOverviewLandingPagesSectionDto"},"topAds":{"$ref":"#/components/schemas/PublicApiBrandtrackerOverviewTopAdsSectionDto"},"adsPreview":{"$ref":"#/components/schemas/PublicApiBrandtrackerOverviewAdsPreviewSectionDto"}},"required":["graph","mediaMix","topLandingPages","topAds","adsPreview"]},"PublicApiGetBrandtrackerOverviewResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerOverviewDto"},"meta":{"type":"object","example":{},"description":"Reserved response metadata. Snapshot freshness is intentionally omitted from overview to match top-ads."}},"required":["requestId","data","meta"]},"PublicApiGetBrandtrackerTimelineResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiAdsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiBrandtrackerTimelineMetadataDto":{"type":"object","properties":{"totalCount":{"type":"number","example":235},"earliestDate":{"type":"string","example":"2026-04-01","format":"date","nullable":true},"latestDate":{"type":"string","example":"2026-04-23","format":"date","nullable":true}},"required":["totalCount","earliestDate","latestDate"]},"PublicApiGetBrandtrackerTimelineMetadataResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimelineMetadataDto"}},"required":["requestId","data"]},"PublicApiBrandtrackerTestingReachStatsDto":{"type":"object","properties":{"min":{"type":"number","example":1200},"avg":{"type":"number","example":4200},"max":{"type":"number","example":9800},"total":{"type":"number","example":16800}},"required":["min","avg","max","total"]},"PublicApiBrandtrackerTestingDaysRunningStatsDto":{"type":"object","properties":{"min":{"type":"number","example":2},"avg":{"type":"number","example":12},"max":{"type":"number","example":31}},"required":["min","avg","max"]},"PublicApiBrandtrackerTestingStatsDto":{"type":"object","properties":{"reach":{"$ref":"#/components/schemas/PublicApiBrandtrackerTestingReachStatsDto"},"daysRunning":{"$ref":"#/components/schemas/PublicApiBrandtrackerTestingDaysRunningStatsDto"},"activeCount":{"type":"number","example":2},"totalCount":{"type":"number","example":4},"bestPerformerId":{"type":"string","nullable":true,"example":"facebook_123456789"}},"required":["reach","daysRunning","activeCount","totalCount","bestPerformerId"]},"PublicApiBrandtrackerTestingBatchDto":{"type":"object","properties":{"startDate":{"type":"string","format":"date","example":"2026-04-20"},"ads":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}},"adsReturned":{"type":"number","example":20,"description":"Number of ads returned in this batch after the per-batch cap."},"maxAdsPerBatch":{"type":"number","example":20,"description":"Maximum ads returned per start-date batch."},"adsTruncated":{"type":"boolean","example":false,"description":"True when more matching ads exist for this start-date batch than were returned."},"runningCount":{"type":"number","example":1},"isWinner":{"type":"boolean","example":true,"description":"True when the batch matches the creative-testing winner heuristics."},"stats":{"$ref":"#/components/schemas/PublicApiBrandtrackerTestingStatsDto"}},"required":["startDate","ads","adsReturned","maxAdsPerBatch","adsTruncated","runningCount","isWinner","stats"]},"PublicApiBrandtrackerTestingPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25,"description":"Number of start-date batches requested per page."},"total":{"type":"number","example":73,"description":"Total matching start-date batches."},"totalPages":{"type":"number","example":3}},"required":["page","limit","total","totalPages"]},"PublicApiGetBrandtrackerTestingResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTestingBatchDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerTestingPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiGetBrandtrackerTimeSeriesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"$ref":"#/components/schemas/PublicApiBrandtrackerTimeSeriesDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"}},"required":["requestId","data","meta"]},"PublicApiBrandtrackerEvolutionDateRangeDto":{"type":"object","properties":{"startDate":{"type":"string","example":"2026-01-01","format":"date"},"endDate":{"type":"string","example":"2026-04-20","format":"date"}},"required":["startDate","endDate"]},"PublicApiBrandtrackerEvolutionPointDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-20","format":"date"},"recordedAt":{"type":"string","example":"2026-04-20T12:30:00.000Z","description":"Timestamp of the history snapshot used for this point."},"activeAds":{"type":"number","example":12},"totalAds":{"type":"number","example":48},"euAds":{"type":"number","example":9},"euActiveAds":{"type":"number","example":7},"totalReach":{"type":"number","example":124500,"description":"Total reach at this history point. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available."},"percentNewAds":{"type":"number","example":18.5}},"required":["date","recordedAt","activeAds","totalAds","euAds","euActiveAds","totalReach","percentNewAds"]},"PublicApiBrandtrackerAdCopyEvolutionSeriesDto":{"type":"object","properties":{"adCopy":{"type":"string","example":"Turn your mornings into a ritual."},"points":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionPointDto"}}},"required":["adCopy","points"]},"PublicApiGetBrandtrackerAdCopyEvolutionResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"dateRange":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionDateRangeDto"},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdCopyEvolutionSeriesDto"}}},"required":["requestId","dateRange","pagination","meta","data"]},"PublicApiBrandtrackerHeadlineEvolutionSeriesDto":{"type":"object","properties":{"headline":{"type":"string","example":"The ritual your skin was waiting for"},"points":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionPointDto"}}},"required":["headline","points"]},"PublicApiGetBrandtrackerHeadlineEvolutionResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"dateRange":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionDateRangeDto"},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerHeadlineEvolutionSeriesDto"}}},"required":["requestId","dateRange","pagination","meta","data"]},"PublicApiBrandtrackerLandingPageEvolutionSeriesDto":{"type":"object","properties":{"landingPage":{"type":"string","example":"https://example.com/products/ritual-kit"},"points":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionPointDto"}}},"required":["landingPage","points"]},"PublicApiGetBrandtrackerLandingPageEvolutionResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"dateRange":{"$ref":"#/components/schemas/PublicApiBrandtrackerEvolutionDateRangeDto"},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiFreshnessMetaDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageEvolutionSeriesDto"}}},"required":["requestId","dateRange","pagination","meta","data"]},"PublicApiBoardCapabilitiesDto":{"type":"object","properties":{"canAddItems":{"type":"boolean"},"canManage":{"type":"boolean"}},"required":["canAddItems","canManage"]},"PublicApiBoardDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["folder","collection"]},"surface":{"type":"string","enum":["ads","shops","landing","emails","products","advertisers"],"nullable":true},"description":{"type":"string","nullable":true},"createdByUserId":{"type":"string"},"parentBoardId":{"type":"string","nullable":true},"workspaceId":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["private","workspace","public"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"type":"string","format":"date-time","nullable":true},"capabilities":{"$ref":"#/components/schemas/PublicApiBoardCapabilitiesDto"}},"required":["id","name","kind","surface","description","createdByUserId","parentBoardId","workspaceId","visibility","createdAt","updatedAt","archivedAt","capabilities"]},"PublicApiBoardsPaginationDto":{"type":"object","properties":{"page":{"type":"number","minimum":1},"limit":{"type":"number","minimum":1},"total":{"type":"number","minimum":0},"totalPages":{"type":"number","minimum":0}},"required":["page","limit","total","totalPages"]},"PublicApiBoardsListResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBoardDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBoardsPaginationDto"}},"required":["requestId","data","pagination"]},"CreatePublicApiBoardBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"kind":{"type":"string","enum":["folder","collection"],"default":"collection"},"surface":{"type":"string","enum":["ads","shops","landing","emails","products","advertisers"],"nullable":true},"description":{"type":"string","maxLength":2000},"visibility":{"type":"string","enum":["private","workspace","public"]},"parentBoardId":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}},"required":["name"]},"PublicApiBoardResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiBoardDto"}},"required":["requestId","data"]},"UpdatePublicApiBoardBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":2000,"nullable":true},"visibility":{"type":"string","enum":["private","workspace","public"]}}},"MovePublicApiBoardBodyDto":{"type":"object","properties":{"parentBoardId":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","nullable":true}},"required":["parentBoardId"]},"PublicApiBoardItemSourceDto":{"type":"object","properties":{"sourceType":{"type":"string"},"sourceId":{"type":"string"},"sourceIndex":{"type":"string"}},"required":["sourceType","sourceId"]},"PublicApiBoardItemDto":{"type":"object","properties":{"id":{"type":"string"},"boardId":{"type":"string"},"savedItemId":{"type":"string","nullable":true},"source":{"$ref":"#/components/schemas/PublicApiBoardItemSourceDto"},"addedByUserId":{"type":"string"},"position":{"type":"number","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","boardId","savedItemId","source","addedByUserId","position","createdAt","updatedAt"]},"PublicApiBoardItemsListResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBoardItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBoardsPaginationDto"}},"required":["requestId","data","pagination"]},"AddPublicApiBoardItemBodyDto":{"type":"object","properties":{"sourceType":{"type":"string","enum":["meta_ad","google_ad","tiktok","shop","email","advertiser"]},"sourceId":{"type":"string","maxLength":255},"sourceIndex":{"type":"string","maxLength":255},"position":{"type":"number","minimum":0}},"required":["sourceType","sourceId"]},"PublicApiAddBoardItemResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiBoardItemDto"},"created":{"type":"boolean"}},"required":["requestId","data","created"]},"MovePublicApiBoardItemBodyDto":{"type":"object","properties":{"targetBoardId":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"position":{"type":"number","minimum":0}},"required":["targetBoardId"]},"PublicApiBoardItemResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiBoardItemDto"}},"required":["requestId","data"]},"PublicApiRemoveBoardItemDataDto":{"type":"object","properties":{"removed":{"type":"boolean"},"boardId":{"type":"string"},"itemId":{"type":"string"}},"required":["removed","boardId","itemId"]},"PublicApiRemoveBoardItemResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiRemoveBoardItemDataDto"}},"required":["requestId","data"]},"PublicApiBoardShareLinkDto":{"type":"object","properties":{"id":{"type":"string"},"boardId":{"type":"string"},"url":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","boardId","url","createdAt"]},"PublicApiBoardShareLinkResponseDto":{"type":"object","properties":{"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/PublicApiBoardShareLinkDto"}},"required":["requestId","data"]},"PublicApiFavoritesScope":{"type":"string","enum":["workspace","personal"]},"AddPublicApiFavoriteAdBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"adId":{"type":"string","example":"facebook_1234567890","description":"Composite public ad identifier, for example facebook_123 or tiktok_123."},"folderId":{"type":"object","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","nullable":true,"description":"Favorite ads folder id (board id, or migrated V2 folder UUID). Null or omitted saves the ad in the scope's \"Unsorted\" board."}},"required":["scope","adId"]},"PublicApiFavoriteAdsFolderDto":{"type":"object","properties":{"id":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Folder id: the id of the board backing the folder."},"name":{"type":"string","example":"Winning Creatives"},"parentId":{"type":"string","example":"board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","nullable":true,"description":"Parent folder (board) id when the folder is nested. Null for root folders."}},"required":["id","name","parentId"]},"PublicApiFavoriteAdItemDto":{"type":"object","properties":{"id":{"type":"string","example":"board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b","description":"Saved favorite id: the board item id."},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"savedAt":{"type":"string","example":"2026-04-20T10:00:00.000Z","format":"date-time"},"folder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDto"}]},"ad":{"nullable":true,"description":"Embedded public ad summary when the backing favorite can be resolved to a public-supported ad platform.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}]}},"required":["id","scope","savedAt","folder","ad"]},"PublicApiFavoriteAdMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteAdItemDto"},"created":{"type":"boolean","example":true,"description":"True when this call created a favorite; false when the favorite already existed."}},"required":["requestId","data","created"]},"MoveSavedPublicApiFavoriteAdBodyDto":{"type":"object","properties":{"folderId":{"type":"object","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","nullable":true,"description":"Favorite ads folder id (board id, or migrated V2 folder UUID). Null moves the saved ad to the scope's \"Unsorted\" board."}}},"PublicApiMoveSavedFavoriteAdResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteAdItemDto"}},"required":["requestId","data"]},"PublicApiRemoveFavoriteAdDataDto":{"type":"object","properties":{"removed":{"type":"boolean","example":true},"adId":{"type":"string","example":"facebook_1234567890"},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"folderId":{"type":"string","nullable":true,"example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e"}},"required":["removed","adId","scope","folderId"]},"PublicApiRemoveFavoriteAdResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteAdDataDto"}},"required":["requestId","data"]},"CreatePublicApiFavoriteAdsFolderBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"name":{"type":"string","example":"Winning Creatives"},"parentId":{"type":"object","example":"f2c0dc30-95bf-4455-bb43-48d5f6e08f30","nullable":true,"description":"Parent folder id (board id, or migrated V2 folder UUID). Null or omitted creates a root folder."}},"required":["scope","name"]},"PublicApiFavoriteAdsFolderMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDto"}},"required":["requestId","data"]},"PublicApiFavoriteAdsFolderOrderItemDto":{"type":"object","properties":{"id":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Favorite ads folder id (board id, or migrated V2 folder UUID)."},"order":{"type":"number","example":1,"minimum":0,"maximum":100000}},"required":["id","order"]},"ReorderPublicApiFavoriteAdsFoldersBodyDto":{"type":"object","properties":{"folders":{"description":"Folder UUID/order pairs to update in the requested scope.","type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderOrderItemDto"}}},"required":["folders"]},"PublicApiReorderFavoriteAdsFoldersDataDto":{"type":"object","properties":{"reordered":{"type":"boolean","example":true},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"folders":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDto"}}},"required":["reordered","scope","folders"]},"PublicApiReorderFavoriteAdsFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiReorderFavoriteAdsFoldersDataDto"}},"required":["requestId","data"]},"PublicApiFavoriteAdsFolderShareDto":{"type":"object","properties":{"folderId":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e","description":"Board id of the shared folder."},"folder":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDto"},"id":{"type":"string","example":"share_3f8aa146-6f96-46e8-9781-64db5166f9a8","description":"Identifier of the board share link."},"slug":{"type":"string","example":null,"nullable":true,"description":"Always null: board share links have no slug."},"shareUrl":{"type":"string","example":"https://app.trendtrack.io/en/share/boards/Zm9vYmFy"},"sharePath":{"type":"string","example":"/en/share/boards/Zm9vYmFy"},"createdAt":{"type":"string","example":"2026-04-18T12:30:00.000Z","format":"date-time"}},"required":["folderId","folder","id","slug","shareUrl","sharePath","createdAt"]},"PublicApiCreateFavoriteAdsFolderShareResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderShareDto"}},"required":["requestId","data"]},"PublicApiFavoriteAdsFolderVisibility":{"type":"string","enum":["private","organization"],"description":"organization publishes a root folder tree to the API credential workspace. private converts a root folder tree to delegated-user personal scope when the delegated user owns all contained folders and saved ads."},"SetPublicApiFavoriteAdsFolderVisibilityBodyDto":{"type":"object","properties":{"visibility":{"example":"organization","description":"organization publishes a root folder tree to the API credential workspace. private converts a root folder tree to delegated-user personal scope when the delegated user owns all contained folders and saved ads.","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderVisibility"}]}},"required":["visibility"]},"UpdatePublicApiFavoriteAdsFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","example":"Top Competitor Hooks"},"parentId":{"type":"object","example":"f2c0dc30-95bf-4455-bb43-48d5f6e08f30","nullable":true,"description":"Parent folder id (board id, or migrated V2 folder UUID). Use null to make it a root folder; omit to keep the current parent."}}},"PublicApiFavoriteAdsFolderDeleteMode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"],"description":"Explicit handling for saved ads contained in the deleted folder tree."},"DeletePublicApiFavoriteAdsFolderBodyDto":{"type":"object","properties":{"mode":{"example":"move_items_to_root","description":"Explicit handling for saved ads contained in the deleted folder tree.","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDeleteMode"}]},"targetFolderId":{"type":"object","example":"f2c0dc30-95bf-4455-bb43-48d5f6e08f30","nullable":true,"description":"Required when mode is move_items_to_folder. Must be a folder in the same requested scope and outside the deleted folder tree."}},"required":["mode"]},"PublicApiDeleteFavoriteAdsFolderDataDto":{"type":"object","properties":{"deleted":{"type":"boolean","example":true},"folderId":{"type":"string","example":"board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e"},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"mode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"]},"targetFolderId":{"type":"string","nullable":true},"deletedFolderIds":{"type":"array","items":{"type":"string"}},"affectedFavoriteIds":{"type":"array","items":{"type":"string"}}},"required":["deleted","folderId","scope","mode","targetFolderId","deletedFolderIds","affectedFavoriteIds"]},"PublicApiDeleteFavoriteAdsFolderResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteAdsFolderDataDto"}},"required":["requestId","data"]},"PublicApiFavoritesPaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":25},"total":{"type":"number","example":130},"totalPages":{"type":"number","example":6}},"required":["page","limit","total","totalPages"]},"PublicApiGetFavoriteAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteAdItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiGetFavoriteAdsFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteAdsFolderDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"AddPublicApiFavoriteShopBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"websiteId":{"type":"string","example":"4af9f0d0-64d3-46db-a5f9-1a1b89604c88","description":"Public website/shop identifier. The server resolves trusted domain and shop metadata from this id; clients cannot supply authoritative domain state."},"folderId":{"type":"object","example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","nullable":true,"description":"Favorite shops folder id (board id, or migrated V2 folder UUID). Null or omitted saves the shop in the scope's \"Unsorted\" board."}},"required":["scope","websiteId"]},"PublicApiFavoriteShopsFolderDto":{"type":"object","properties":{"id":{"type":"string","example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","description":"Folder id: the id of the board backing the folder."},"name":{"type":"string","example":"Competitors"}},"required":["id","name"]},"PublicApiFavoriteShopItemDto":{"type":"object","properties":{"id":{"type":"string","example":"board_item_8f92ad4a-61e8-4519-a182-4f8e24db0e52","description":"Saved favorite id: the board item id."},"scope":{"type":"string","enum":["workspace","personal"],"example":"personal"},"savedAt":{"type":"string","example":"2026-04-20T10:00:00.000Z","format":"date-time"},"folder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderDto"}]},"shop":{"$ref":"#/components/schemas/PublicApiShopSummaryDto"}},"required":["id","scope","savedAt","folder","shop"]},"PublicApiFavoriteShopMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteShopItemDto"},"created":{"type":"boolean","example":true,"description":"True when this call created a favorite; false when the favorite already existed."}},"required":["requestId","data","created"]},"MoveSavedPublicApiFavoriteShopBodyDto":{"type":"object","properties":{"folderId":{"type":"object","example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","nullable":true,"description":"Favorite shops folder id (board id, or migrated V2 folder UUID). Null moves the saved shop to the scope's \"Unsorted\" board."}}},"PublicApiMoveSavedFavoriteShopResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteShopItemDto"}},"required":["requestId","data"]},"PublicApiRemoveFavoriteShopDataDto":{"type":"object","properties":{"removed":{"type":"boolean","example":true},"websiteId":{"type":"string","example":"4af9f0d0-64d3-46db-a5f9-1a1b89604c88"},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"folderId":{"type":"string","nullable":true,"example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca"},"savedFavoriteId":{"type":"string","nullable":true,"example":"8f92ad4a-61e8-4519-a182-4f8e24db0e52"}},"required":["removed","websiteId","scope","folderId","savedFavoriteId"]},"PublicApiRemoveFavoriteShopResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteShopDataDto"}},"required":["requestId","data"]},"CreatePublicApiFavoriteShopsFolderBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"name":{"type":"string","example":"Competitors"}},"required":["scope","name"]},"PublicApiFavoriteShopsFolderMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderDto"}},"required":["requestId","data"]},"PublicApiFavoriteShopsFolderVisibility":{"type":"string","enum":["private","organization"],"description":"organization publishes a flat shop folder to the API credential workspace. private converts it to delegated-user personal scope when the delegated user owns the folder and every contained saved shop."},"SetPublicApiFavoriteShopsFolderVisibilityBodyDto":{"type":"object","properties":{"visibility":{"example":"organization","description":"organization publishes a flat shop folder to the API credential workspace. private converts it to delegated-user personal scope when the delegated user owns the folder and every contained saved shop.","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderVisibility"}]}},"required":["visibility"]},"UpdatePublicApiFavoriteShopsFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","example":"Top Competitors"}}},"PublicApiFavoriteShopsFolderDeleteMode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"],"description":"Explicit handling for saved shops contained in the deleted flat folder."},"DeletePublicApiFavoriteShopsFolderBodyDto":{"type":"object","properties":{"mode":{"example":"move_items_to_root","description":"Explicit handling for saved shops contained in the deleted flat folder.","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderDeleteMode"}]},"targetFolderId":{"type":"object","example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca","nullable":true,"description":"Required when mode is move_items_to_folder. Must be a flat shops folder in the same requested scope."}},"required":["mode"]},"PublicApiDeleteFavoriteShopsFolderDataDto":{"type":"object","properties":{"deleted":{"type":"boolean","example":true},"folderId":{"type":"string","example":"board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca"},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"mode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"]},"targetFolderId":{"type":"string","nullable":true},"affectedFavoriteIds":{"type":"array","items":{"type":"string"}}},"required":["deleted","folderId","scope","mode","targetFolderId","affectedFavoriteIds"]},"PublicApiDeleteFavoriteShopsFolderResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteShopsFolderDataDto"}},"required":["requestId","data"]},"PublicApiGetFavoriteShopsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteShopItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiGetFavoriteShopsFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteShopsFolderDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"AddPublicApiFavoriteEmailBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"emailId":{"type":"number","example":7298813,"description":"Public email identifier used by search/get_email_html."},"folderId":{"type":"object","example":"0e91fbef-3d02-44d8-b024-3bda62fb050c","nullable":true,"description":"Favorite emails folder id (board id, or migrated V2 folder UUID). Null or omitted saves the email in the scope's \"Unsorted\" board."}},"required":["scope","emailId"]},"PublicApiFavoriteEmailsFolderDto":{"type":"object","properties":{"id":{"type":"string","example":"board_0e91fbef-3d02-44d8-b024-3bda62fb050c","description":"Folder id: the id of the board backing the folder."},"name":{"type":"string","example":"Lifecycle Emails"},"parentId":{"type":"string","example":"board_4b84a8f9-44df-4a18-9f08-66e6db6403da","nullable":true,"description":"Parent folder (board) id. Null for root folders."}},"required":["id","name","parentId"]},"PublicApiFavoriteEmailItemDto":{"type":"object","properties":{"id":{"type":"string","example":"board_item_f3d7c2da-e64c-42c3-a0b1-ef1a4633592d","description":"Saved favorite id: the board item id."},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"savedAt":{"type":"string","example":"2026-04-20T10:00:00.000Z","format":"date-time"},"folder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderDto"}]},"email":{"nullable":true,"description":"Embedded public email summary. Null when the saved row exists but the backing email content is no longer available.","type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiEmailSummaryDto"}]}},"required":["id","scope","savedAt","folder","email"]},"PublicApiFavoriteEmailMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteEmailItemDto"},"created":{"type":"boolean","example":true}},"required":["requestId","data","created"]},"MoveSavedPublicApiFavoriteEmailBodyDto":{"type":"object","properties":{"folderId":{"type":"object","example":"0e91fbef-3d02-44d8-b024-3bda62fb050c","nullable":true,"description":"Favorite emails folder id (board id, or migrated V2 folder UUID). Null moves the saved email to the scope's \"Unsorted\" board."}}},"PublicApiMoveSavedFavoriteEmailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteEmailItemDto"}},"required":["requestId","data"]},"PublicApiRemoveFavoriteEmailDataDto":{"type":"object","properties":{"removed":{"type":"boolean","example":true},"emailId":{"type":"number","example":7298813},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"folderId":{"type":"string","nullable":true,"example":"0e91fbef-3d02-44d8-b024-3bda62fb050c"},"savedFavoriteId":{"type":"string","example":"f3d7c2da-e64c-42c3-a0b1-ef1a4633592d"}},"required":["removed","emailId","scope","folderId","savedFavoriteId"]},"PublicApiRemoveFavoriteEmailResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiRemoveFavoriteEmailDataDto"}},"required":["requestId","data"]},"CreatePublicApiFavoriteEmailsFolderBodyDto":{"type":"object","properties":{"scope":{"example":"workspace","allOf":[{"$ref":"#/components/schemas/PublicApiFavoritesScope"}]},"name":{"type":"string","example":"Lifecycle Emails"},"parentId":{"type":"object","example":"4b84a8f9-44df-4a18-9f08-66e6db6403da","nullable":true,"description":"Parent folder id (board id, or migrated V2 folder UUID). Null or omitted creates a root folder."}},"required":["scope","name"]},"PublicApiFavoriteEmailsFolderMutationResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderDto"}},"required":["requestId","data"]},"PublicApiFavoriteEmailsFolderOrderItemDto":{"type":"object","properties":{"id":{"type":"string","example":"0e91fbef-3d02-44d8-b024-3bda62fb050c","description":"Favorite emails folder id (board id, or migrated V2 folder UUID)."},"order":{"type":"number","example":1,"minimum":0,"maximum":100000}},"required":["id","order"]},"ReorderPublicApiFavoriteEmailsFoldersBodyDto":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderOrderItemDto"}}},"required":["folders"]},"PublicApiReorderFavoriteEmailsFoldersDataDto":{"type":"object","properties":{"reordered":{"type":"boolean","example":true},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"folders":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderDto"}}},"required":["reordered","scope","folders"]},"PublicApiReorderFavoriteEmailsFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiReorderFavoriteEmailsFoldersDataDto"}},"required":["requestId","data"]},"PublicApiFavoriteEmailsFolderVisibility":{"type":"string","enum":["private","organization"],"description":"organization publishes a root email folder tree to the API credential workspace. private converts it to delegated-user personal scope when the delegated user owns every contained folder and saved email."},"SetPublicApiFavoriteEmailsFolderVisibilityBodyDto":{"type":"object","properties":{"visibility":{"example":"organization","description":"organization publishes a root email folder tree to the API credential workspace. private converts it to delegated-user personal scope when the delegated user owns every contained folder and saved email.","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderVisibility"}]}},"required":["visibility"]},"UpdatePublicApiFavoriteEmailsFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","example":"VIP Lifecycle Emails"},"parentId":{"type":"object","example":"4b84a8f9-44df-4a18-9f08-66e6db6403da","nullable":true,"description":"Parent folder id (board id, or migrated V2 folder UUID). Use null to make it a root folder; omit to keep the current parent."}}},"PublicApiFavoriteEmailsFolderDeleteMode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"]},"DeletePublicApiFavoriteEmailsFolderBodyDto":{"type":"object","properties":{"mode":{"example":"move_items_to_root","allOf":[{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderDeleteMode"}]},"targetFolderId":{"type":"object","example":"4b84a8f9-44df-4a18-9f08-66e6db6403da","nullable":true}},"required":["mode"]},"PublicApiDeleteFavoriteEmailsFolderDataDto":{"type":"object","properties":{"deleted":{"type":"boolean","example":true},"folderId":{"type":"string","example":"0e91fbef-3d02-44d8-b024-3bda62fb050c"},"scope":{"type":"string","enum":["workspace","personal"],"example":"workspace"},"mode":{"type":"string","enum":["delete_items","move_items_to_root","move_items_to_folder"]},"targetFolderId":{"type":"string","nullable":true},"deletedFolderIds":{"type":"array","items":{"type":"string"}},"affectedFavoriteIds":{"type":"array","items":{"type":"string"}}},"required":["deleted","folderId","scope","mode","targetFolderId","deletedFolderIds","affectedFavoriteIds"]},"PublicApiDeleteFavoriteEmailsFolderResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"$ref":"#/components/schemas/PublicApiDeleteFavoriteEmailsFolderDataDto"}},"required":["requestId","data"]},"PublicApiGetFavoriteEmailsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteEmailItemDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiGetFavoriteEmailsFoldersResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiFavoriteEmailsFolderDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiFavoritesPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceTopAdsPeriod":{"type":"string","enum":["today","yesterday","last1d","last7d","last14d","last30d","total"]},"PublicApiWorkspaceTopAdsBrandtrackerDto":{"type":"object","properties":{"id":{"type":"string","example":"1e08fa85-625a-4ba5-b673-d2a4b7bc7c55","description":"Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists."},"name":{"type":"string","example":"Acme"},"facebookPageId":{"type":"string","example":"123456789012345","description":"Facebook page id associated with this workspace brandtracker."}},"required":["id","name","facebookPageId"]},"PublicApiWorkspaceTopAdDto":{"type":"object","properties":{"brandtracker":{"allOf":[{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"}],"description":"Brandtracker context for this workspace top-ads row. Each row is nested as { brandtracker, ad, metrics }."},"ad":{"allOf":[{"$ref":"#/components/schemas/PublicApiAdSummaryDto"}],"description":"Ad summary payload for this workspace top-ads row. Each row is nested as { brandtracker, ad, metrics }."},"metrics":{"allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerTopAdMetricsDto"}],"description":"Ranking/reach metrics for this workspace top-ads row. Each row is nested as { brandtracker, ad, metrics }."}},"required":["brandtracker","ad","metrics"]},"PublicApiGetWorkspaceTopAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc","description":"Request identifier mirrored in the X-Request-Id response header."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdDto"},"description":"Workspace top-ads rows. Every element uses the nested shape { brandtracker, ad, metrics }."},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"},"meta":{"$ref":"#/components/schemas/PublicApiTopAdsMetaDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceHookResourceDto":{"type":"object","properties":{"text":{"type":"string","example":"Stop scrolling."},"sampleAd":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerHookSampleAdDto"}]}},"required":["text","sampleAd"]},"PublicApiWorkspaceHookMetricsDto":{"type":"object","properties":{"usageCount":{"type":"number","example":12},"longestRunning":{"type":"number","example":47},"totalImpressions":{"type":"number","example":152340},"firstUsedAt":{"type":"string","nullable":true,"format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["usageCount","longestRunning","totalImpressions","firstUsedAt","lastUsedAt"]},"PublicApiWorkspaceHookDto":{"type":"object","properties":{"brandtracker":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"},"hook":{"$ref":"#/components/schemas/PublicApiWorkspaceHookResourceDto"},"metrics":{"$ref":"#/components/schemas/PublicApiWorkspaceHookMetricsDto"}},"required":["brandtracker","hook","metrics"]},"PublicApiGetWorkspaceHooksResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceHookDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceAdCopyResourceDto":{"type":"object","properties":{"text":{"type":"string","example":"Get 30% off selected products this week only."}},"required":["text"]},"PublicApiWorkspaceAdCopyMetricsDto":{"type":"object","properties":{"usageCount":{"type":"number","example":21},"longestRunning":{"type":"number","example":43}},"required":["usageCount","longestRunning"]},"PublicApiWorkspaceAdCopyDto":{"type":"object","properties":{"brandtracker":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"},"adCopy":{"$ref":"#/components/schemas/PublicApiWorkspaceAdCopyResourceDto"},"metrics":{"$ref":"#/components/schemas/PublicApiWorkspaceAdCopyMetricsDto"}},"required":["brandtracker","adCopy","metrics"]},"PublicApiGetWorkspaceAdCopiesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceAdCopyDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceLandingPageResourceDto":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/products/summer-sale"},"technologies":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerTechnologyDto"}},"screenshots":{"$ref":"#/components/schemas/PublicApiBrandtrackerLandingPageScreenshotsDto"}},"required":["url","technologies","screenshots"]},"PublicApiWorkspaceLandingPageMetricsDto":{"type":"object","properties":{"usageCount":{"type":"number","example":16},"longestRunning":{"type":"number","example":41},"totalImpressions":{"type":"number","example":305400}},"required":["usageCount","longestRunning","totalImpressions"]},"PublicApiWorkspaceLandingPageDto":{"type":"object","properties":{"brandtracker":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"},"landingPage":{"$ref":"#/components/schemas/PublicApiWorkspaceLandingPageResourceDto"},"metrics":{"$ref":"#/components/schemas/PublicApiWorkspaceLandingPageMetricsDto"}},"required":["brandtracker","landingPage","metrics"]},"PublicApiGetWorkspaceLandingPagesResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceLandingPageDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceAggregatePeriod":{"type":"string","enum":["today","yesterday","last1d","last7d","last14d","last30d","total"]},"PublicApiWorkspaceScalingAdDto":{"type":"object","properties":{"brandtracker":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"},"ad":{"$ref":"#/components/schemas/PublicApiAdSummaryDto"},"metrics":{"$ref":"#/components/schemas/PublicApiBrandtrackerScalingAdMetricsDto"},"trajectory":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiBrandtrackerAdRankTrajectoryPointDto"}}},"required":["brandtracker","ad","metrics","trajectory"]},"PublicApiGetWorkspaceScalingAdsResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceScalingAdDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]},"PublicApiWorkspaceMediaMixSortBy":{"type":"string","enum":["activeAds","image","video","dco","other"]},"PublicApiWorkspaceMediaMixResourceDto":{"type":"object","properties":{"formatCount":{"allOf":[{"$ref":"#/components/schemas/PublicApiBrandtrackerMediaMixFormatCountDto"}],"description":"Workspace media mix exposes image, video, dco, and other only. Carousel is not available as a separate bucket."}},"required":["formatCount"]},"PublicApiWorkspaceMediaMixMetricsDto":{"type":"object","properties":{"activeAds":{"type":"number","example":23}},"required":["activeAds"]},"PublicApiWorkspaceMediaMixDto":{"type":"object","properties":{"brandtracker":{"$ref":"#/components/schemas/PublicApiWorkspaceTopAdsBrandtrackerDto"},"mediaMix":{"$ref":"#/components/schemas/PublicApiWorkspaceMediaMixResourceDto"},"metrics":{"$ref":"#/components/schemas/PublicApiWorkspaceMediaMixMetricsDto"}},"required":["brandtracker","mediaMix","metrics"]},"PublicApiGetWorkspaceMediaMixResponseDto":{"type":"object","properties":{"requestId":{"type":"string","example":"5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiWorkspaceMediaMixDto"}},"pagination":{"$ref":"#/components/schemas/PublicApiBrandtrackerInsightsPaginationDto"}},"required":["requestId","data","pagination"]}}}}