Trendtrack
ReferenceAPI

Favorites

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer
folderId?string

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.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/ads?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b",      "scope": "workspace",      "savedAt": "2026-04-20T10:00:00.000Z",      "folder": {        "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",        "name": "Winning Creatives",        "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"      },      "ad": {        "id": "facebook_123456789",        "collationId": "3810635369204881",        "platform": "facebook",        "status": "active",        "createdAt": "2026-04-18T12:30:00.000Z",        "firstSeenAt": "2026-04-10T00:00:00.000Z",        "lastSeenAt": "2026-04-19T00:00:00.000Z",        "daysRunning": 9,        "media": {          "type": "video",          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"        },        "advertiser": {          "id": "1234567890",          "name": "Example Brand",          "logoUrl": "https://cdn.example.com/pages/example-brand.png",          "facebookPageId": "1234567890",          "liveAdsCount": 42,          "reach30d": 152340,          "totalReach": 842100,          "countriesCount": 8,          "facebookLikes": 125000,          "instagramFollowers": 89000        },        "content": {          "title": "Summer Sale",          "body": "Up to 30% off selected products.",          "transcript": "Save 30% on every order.",          "callToAction": "Shop now",          "landingPageUrl": "https://example.com/products/summer-sale",          "landingPageDomain": "example.com",          "ctaDescription": "Free shipping on orders over $50.",          "ctaLinkDescription": "Shop the full collection"        },        "metrics": {          "reach": 152340,          "aggregatedReach": 284100,          "estimatedSpend": 4262,          "duplicates": 4,          "reachDelta1d": 1200,          "reachDelta7d": 8200,          "reachDelta30d": 38400        },        "audience": {          "targetedCountries": [            "US",            "FR"          ],          "mainCountry": "FR",          "gender": "all",          "ageMin": 18,          "ageMax": 65        },        "rank": {          "positionInPage": 3,          "currentRank": 12,          "rankDelta": -4,          "improvementPct": 0.25        },        "flags": {          "isEuAd": true,          "isLowReach": false,          "isMediaChanged": false,          "hasPartnerBadge": true        }      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
adId*string

Composite public ad identifier, for example facebook_123 or tiktok_123.

folderId?|

Favorite ads folder id (board id, or migrated V2 folder UUID). Null or omitted saves the ad in the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/ads" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "adId": "facebook_1234567890"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b",    "scope": "workspace",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",      "name": "Winning Creatives",      "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"    },    "ad": {      "id": "facebook_123456789",      "collationId": "3810635369204881",      "platform": "facebook",      "status": "active",      "createdAt": "2026-04-18T12:30:00.000Z",      "firstSeenAt": "2026-04-10T00:00:00.000Z",      "lastSeenAt": "2026-04-19T00:00:00.000Z",      "daysRunning": 9,      "media": {        "type": "video",        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"      },      "advertiser": {        "id": "1234567890",        "name": "Example Brand",        "logoUrl": "https://cdn.example.com/pages/example-brand.png",        "facebookPageId": "1234567890",        "liveAdsCount": 42,        "reach30d": 152340,        "totalReach": 842100,        "countriesCount": 8,        "facebookLikes": 125000,        "instagramFollowers": 89000      },      "content": {        "title": "Summer Sale",        "body": "Up to 30% off selected products.",        "transcript": "Save 30% on every order.",        "callToAction": "Shop now",        "landingPageUrl": "https://example.com/products/summer-sale",        "landingPageDomain": "example.com",        "ctaDescription": "Free shipping on orders over $50.",        "ctaLinkDescription": "Shop the full collection"      },      "metrics": {        "reach": 152340,        "aggregatedReach": 284100,        "estimatedSpend": 4262,        "duplicates": 4,        "reachDelta1d": 1200,        "reachDelta7d": 8200,        "reachDelta30d": 38400      },      "audience": {        "targetedCountries": [          "US",          "FR"        ],        "mainCountry": "FR",        "gender": "all",        "ageMin": 18,        "ageMax": 65      },      "rank": {        "positionInPage": 3,        "currentRank": 12,        "rankDelta": -4,        "improvementPct": 0.25      },      "flags": {        "isEuAd": true,        "isLowReach": false,        "isMediaChanged": false,        "hasPartnerBadge": true      }    }  },  "created": true}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Favorite ads folder id (board id, or migrated V2 folder UUID). Null moves the saved ad to the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/ads/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b",    "scope": "workspace",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",      "name": "Winning Creatives",      "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"    },    "ad": {      "id": "facebook_123456789",      "collationId": "3810635369204881",      "platform": "facebook",      "status": "active",      "createdAt": "2026-04-18T12:30:00.000Z",      "firstSeenAt": "2026-04-10T00:00:00.000Z",      "lastSeenAt": "2026-04-19T00:00:00.000Z",      "daysRunning": 9,      "media": {        "type": "video",        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"      },      "advertiser": {        "id": "1234567890",        "name": "Example Brand",        "logoUrl": "https://cdn.example.com/pages/example-brand.png",        "facebookPageId": "1234567890",        "liveAdsCount": 42,        "reach30d": 152340,        "totalReach": 842100,        "countriesCount": 8,        "facebookLikes": 125000,        "instagramFollowers": 89000      },      "content": {        "title": "Summer Sale",        "body": "Up to 30% off selected products.",        "transcript": "Save 30% on every order.",        "callToAction": "Shop now",        "landingPageUrl": "https://example.com/products/summer-sale",        "landingPageDomain": "example.com",        "ctaDescription": "Free shipping on orders over $50.",        "ctaLinkDescription": "Shop the full collection"      },      "metrics": {        "reach": 152340,        "aggregatedReach": 284100,        "estimatedSpend": 4262,        "duplicates": 4,        "reachDelta1d": 1200,        "reachDelta7d": 8200,        "reachDelta30d": 38400      },      "audience": {        "targetedCountries": [          "US",          "FR"        ],        "mainCountry": "FR",        "gender": "all",        "ageMin": 18,        "ageMax": 65      },      "rank": {        "positionInPage": 3,        "currentRank": 12,        "rankDelta": -4,        "improvementPct": 0.25      },      "flags": {        "isEuAd": true,        "isLowReach": false,        "isMediaChanged": false,        "hasPartnerBadge": true      }    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/ads/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "adId": "facebook_1234567890",    "scope": "workspace",    "folderId": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

adId*string

Composite public ad identifier, for example facebook_123 or tiktok_123.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

folderId?string

Favorite ads folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/ads/string?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "adId": "facebook_1234567890",    "scope": "workspace",    "folderId": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer
parentId?string

Optional parent folder id (board id, or migrated V2 folder UUID). When provided, only direct children of that folder are returned.

rootOnly?boolean

When true, returns only root folders. Cannot be combined with parentId.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/ads/folders?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",      "name": "Winning Creatives",      "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
name*string
parentId?|

Parent folder id (board id, or migrated V2 folder UUID). Null or omitted creates a root folder.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/ads/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Winning Creatives"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",    "name": "Winning Creatives",    "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folders*array<>

Folder UUID/order pairs to update in the requested scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/ads/folders/reorder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "folders": [      {        "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",        "order": 1      }    ]  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "reordered": true,    "scope": "workspace",    "folders": [      {        "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",        "name": "Winning Creatives",        "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"      }    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/ads/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e/share?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "folderId": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",    "folder": {      "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",      "name": "Winning Creatives",      "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"    },    "id": "share_3f8aa146-6f96-46e8-9781-64db5166f9a8",    "slug": null,    "shareUrl": "https://app.trendtrack.io/en/share/boards/Zm9vYmFy",    "sharePath": "/en/share/boards/Zm9vYmFy",    "createdAt": "2026-04-18T12:30:00.000Z"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

visibility*string

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.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/ads/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",    "name": "Winning Creatives",    "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string
parentId?|

Parent folder id (board id, or migrated V2 folder UUID). Use null to make it a root folder; omit to keep the current parent.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/ads/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",    "name": "Winning Creatives",    "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Explicit handling for saved ads contained in the deleted folder tree.

targetFolderId?|

Required when mode is move_items_to_folder. Must be a folder in the same requested scope and outside the deleted folder tree.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/ads/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "mode": "move_items_to_root"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "deleted": true,    "folderId": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",    "scope": "workspace",    "mode": "delete_items",    "targetFolderId": "string",    "deletedFolderIds": [      "string"    ],    "affectedFavoriteIds": [      "string"    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer
folderId?string

Optional shops folder identifier. When provided, only favorites saved in that folder are returned.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/shops?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_item_8f92ad4a-61e8-4519-a182-4f8e24db0e52",      "scope": "personal",      "savedAt": "2026-04-20T10:00:00.000Z",      "folder": {        "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",        "name": "Competitors"      },      "shop": {        "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",        "domain": "example.com",        "name": "Example Shop",        "screenshotUrl": "https://cdn.example.com/screenshots/example.com.png",        "createdAt": "2024-01-15T00:00:00.000Z",        "profile": {          "countryCode": "US",          "currency": "USD",          "isShopifyPlus": true        },        "catalog": {          "productsCount": 124,          "mainCategory": "Fashion",          "bestSellers": [            {              "imageUrl": "https://cdn.shopify.com/s/files/1/1442/3288/files/PDP_QUIET_WHITE_01-805740.png",              "title": "Loop Quiet™ 2",              "price": 19.95,              "currency": "EUR"            }          ]        },        "traffic": {          "monthlyVisits": 45231,          "growth30d": 0.18,          "history": [            {              "period": "2026-03-01",              "value": 2942350            }          ],          "topCountries": [            {              "countryCode": "US",              "share": 0.64            }          ]        },        "sales": {          "currency": "USD",          "estMonthlySales": 222540,          "unitsSold": 1823        },        "advertising": {          "totalAds": 18185,          "activeAds": 12,          "linkedAdvertisersCount": 2,          "history": [            {              "period": "2026-03-01",              "value": 2942350            }          ],          "topCountries": [            {              "countryCode": "US",              "share": 0.64            }          ]        },        "tiktok": {          "hasTikTok": true,          "pageId": "6802334614847603717",          "handle": "examplebrand",          "profileMetrics": {            "followers": 128430,            "totalPosts": 342,            "newPosts": 12,            "totalViews": 9823431,            "totalLikes": 456789          },          "activity": {            "activeAds": 7,            "totalAds": 33,            "avgActiveAds7d": 5.5,            "avgActiveAds30d": 4.25          },          "lastUpdatedAt": "2026-06-05T08:30:00.000Z"        },        "googleAds": {          "status": "available",          "liveAds": 14,          "adsLaunched30d": 5,          "reach": {            "value": 245000,            "label": "Google reported reach",            "euUkOnly": false          },          "topCountries": [            {              "code": "FR",              "ads": 12,              "reach": 185000            }          ],          "platformMix": [            {              "platform": "SEARCH",              "ads": 8            }          ]        },        "latestAds": [          {            "id": "facebook_1059447873925448",            "mediaType": "video",            "mediaUrl": "https://medias.trendtrack.io/video/facebook/1317841346869775.mp4",            "thumbnailUrl": "https://medias.trendtrack.io/thumbnails/facebook/1317841346869775.jpg"          }        ],        "details": {          "trustpilot": {            "rating": 4.3,            "reviewCount": 1280          },          "socials": {            "totalFollowers": 426558,            "facebookLikes": 79431,            "instagramFollowers": 339083,            "tiktokFollowers": 8044          },          "apps": [            {              "id": "da731807-3667-4cc4-8ea0-39727b50b2d5",              "label": "Klaviyo",              "iconUrl": "string"            }          ],          "adReach": 1250000,          "bestSellersAvgPrice": {            "amount": 76.85,            "currency": "USD"          }        }      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
websiteId*string

Public website/shop identifier. The server resolves trusted domain and shop metadata from this id; clients cannot supply authoritative domain state.

folderId?|

Favorite shops folder id (board id, or migrated V2 folder UUID). Null or omitted saves the shop in the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/shops" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "websiteId": "4af9f0d0-64d3-46db-a5f9-1a1b89604c88"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_8f92ad4a-61e8-4519-a182-4f8e24db0e52",    "scope": "personal",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",      "name": "Competitors"    },    "shop": {      "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",      "domain": "example.com",      "name": "Example Shop",      "screenshotUrl": "https://cdn.example.com/screenshots/example.com.png",      "createdAt": "2024-01-15T00:00:00.000Z",      "profile": {        "countryCode": "US",        "currency": "USD",        "isShopifyPlus": true      },      "catalog": {        "productsCount": 124,        "mainCategory": "Fashion",        "bestSellers": [          {            "imageUrl": "https://cdn.shopify.com/s/files/1/1442/3288/files/PDP_QUIET_WHITE_01-805740.png",            "title": "Loop Quiet™ 2",            "price": 19.95,            "currency": "EUR"          }        ]      },      "traffic": {        "monthlyVisits": 45231,        "growth30d": 0.18,        "history": [          {            "period": "2026-03-01",            "value": 2942350          }        ],        "topCountries": [          {            "countryCode": "US",            "share": 0.64          }        ]      },      "sales": {        "currency": "USD",        "estMonthlySales": 222540,        "unitsSold": 1823      },      "advertising": {        "totalAds": 18185,        "activeAds": 12,        "linkedAdvertisersCount": 2,        "history": [          {            "period": "2026-03-01",            "value": 2942350          }        ],        "topCountries": [          {            "countryCode": "US",            "share": 0.64          }        ]      },      "tiktok": {        "hasTikTok": true,        "pageId": "6802334614847603717",        "handle": "examplebrand",        "profileMetrics": {          "followers": 128430,          "totalPosts": 342,          "newPosts": 12,          "totalViews": 9823431,          "totalLikes": 456789        },        "activity": {          "activeAds": 7,          "totalAds": 33,          "avgActiveAds7d": 5.5,          "avgActiveAds30d": 4.25        },        "lastUpdatedAt": "2026-06-05T08:30:00.000Z"      },      "googleAds": {        "status": "available",        "liveAds": 14,        "adsLaunched30d": 5,        "reach": {          "value": 245000,          "label": "Google reported reach",          "euUkOnly": false        },        "topCountries": [          {            "code": "FR",            "ads": 12,            "reach": 185000          }        ],        "platformMix": [          {            "platform": "SEARCH",            "ads": 8          }        ]      },      "latestAds": [        {          "id": "facebook_1059447873925448",          "mediaType": "video",          "mediaUrl": "https://medias.trendtrack.io/video/facebook/1317841346869775.mp4",          "thumbnailUrl": "https://medias.trendtrack.io/thumbnails/facebook/1317841346869775.jpg"        }      ],      "details": {        "trustpilot": {          "rating": 4.3,          "reviewCount": 1280        },        "socials": {          "totalFollowers": 426558,          "facebookLikes": 79431,          "instagramFollowers": 339083,          "tiktokFollowers": 8044        },        "apps": [          {            "id": "da731807-3667-4cc4-8ea0-39727b50b2d5",            "label": "Klaviyo",            "iconUrl": "string"          }        ],        "adReach": 1250000,        "bestSellersAvgPrice": {          "amount": 76.85,          "currency": "USD"        }      }    }  },  "created": true}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Favorite shops folder id (board id, or migrated V2 folder UUID). Null moves the saved shop to the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/shops/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_8f92ad4a-61e8-4519-a182-4f8e24db0e52",    "scope": "personal",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",      "name": "Competitors"    },    "shop": {      "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",      "domain": "example.com",      "name": "Example Shop",      "screenshotUrl": "https://cdn.example.com/screenshots/example.com.png",      "createdAt": "2024-01-15T00:00:00.000Z",      "profile": {        "countryCode": "US",        "currency": "USD",        "isShopifyPlus": true      },      "catalog": {        "productsCount": 124,        "mainCategory": "Fashion",        "bestSellers": [          {            "imageUrl": "https://cdn.shopify.com/s/files/1/1442/3288/files/PDP_QUIET_WHITE_01-805740.png",            "title": "Loop Quiet™ 2",            "price": 19.95,            "currency": "EUR"          }        ]      },      "traffic": {        "monthlyVisits": 45231,        "growth30d": 0.18,        "history": [          {            "period": "2026-03-01",            "value": 2942350          }        ],        "topCountries": [          {            "countryCode": "US",            "share": 0.64          }        ]      },      "sales": {        "currency": "USD",        "estMonthlySales": 222540,        "unitsSold": 1823      },      "advertising": {        "totalAds": 18185,        "activeAds": 12,        "linkedAdvertisersCount": 2,        "history": [          {            "period": "2026-03-01",            "value": 2942350          }        ],        "topCountries": [          {            "countryCode": "US",            "share": 0.64          }        ]      },      "tiktok": {        "hasTikTok": true,        "pageId": "6802334614847603717",        "handle": "examplebrand",        "profileMetrics": {          "followers": 128430,          "totalPosts": 342,          "newPosts": 12,          "totalViews": 9823431,          "totalLikes": 456789        },        "activity": {          "activeAds": 7,          "totalAds": 33,          "avgActiveAds7d": 5.5,          "avgActiveAds30d": 4.25        },        "lastUpdatedAt": "2026-06-05T08:30:00.000Z"      },      "googleAds": {        "status": "available",        "liveAds": 14,        "adsLaunched30d": 5,        "reach": {          "value": 245000,          "label": "Google reported reach",          "euUkOnly": false        },        "topCountries": [          {            "code": "FR",            "ads": 12,            "reach": 185000          }        ],        "platformMix": [          {            "platform": "SEARCH",            "ads": 8          }        ]      },      "latestAds": [        {          "id": "facebook_1059447873925448",          "mediaType": "video",          "mediaUrl": "https://medias.trendtrack.io/video/facebook/1317841346869775.mp4",          "thumbnailUrl": "https://medias.trendtrack.io/thumbnails/facebook/1317841346869775.jpg"        }      ],      "details": {        "trustpilot": {          "rating": 4.3,          "reviewCount": 1280        },        "socials": {          "totalFollowers": 426558,          "facebookLikes": 79431,          "instagramFollowers": 339083,          "tiktokFollowers": 8044        },        "apps": [          {            "id": "da731807-3667-4cc4-8ea0-39727b50b2d5",            "label": "Klaviyo",            "iconUrl": "string"          }        ],        "adReach": 1250000,        "bestSellersAvgPrice": {          "amount": 76.85,          "currency": "USD"        }      }    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/shops/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "websiteId": "4af9f0d0-64d3-46db-a5f9-1a1b89604c88",    "scope": "workspace",    "folderId": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "savedFavoriteId": "8f92ad4a-61e8-4519-a182-4f8e24db0e52"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

websiteId*string

Public website/shop identifier.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

folderId?string

Favorite shops folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/shops/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "websiteId": "4af9f0d0-64d3-46db-a5f9-1a1b89604c88",    "scope": "workspace",    "folderId": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "savedFavoriteId": "8f92ad4a-61e8-4519-a182-4f8e24db0e52"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/shops/folders?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",      "name": "Competitors"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
name*string

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/shops/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Competitors"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "name": "Competitors"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

visibility*string

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.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/shops/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "name": "Competitors"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/shops/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "name": "Competitors"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Explicit handling for saved shops contained in the deleted flat folder.

targetFolderId?|

Required when mode is move_items_to_folder. Must be a flat shops folder in the same requested scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/shops/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "mode": "move_items_to_root"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "deleted": true,    "folderId": "board_5c11c47c-cf92-4709-85a2-a1f72b9ea0ca",    "scope": "workspace",    "mode": "delete_items",    "targetFolderId": "string",    "affectedFavoriteIds": [      "string"    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer
folderId?string

Optional emails folder id (board id, or migrated V2 folder UUID). When provided, only favorites saved in that folder are returned.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/emails?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_item_f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",      "scope": "workspace",      "savedAt": "2026-04-20T10:00:00.000Z",      "folder": {        "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",        "name": "Lifecycle Emails",        "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"      },      "email": {        "id": 123456,        "sentAt": "2026-04-18T12:30:00.000Z",        "campaignType": "Newsletter",        "classification": {          "promotionType": "Discount %",          "promotionTypeId": 1,          "category": "Promotional Campaign",          "categoryId": 4,          "event": {            "name": "Black Friday",            "id": 1,            "category": "Commercial Events"          }        },        "content": {          "subject": "Up to 30% off this weekend",          "preheader": "Limited-time offers picked for you.",          "bodyPreview": "Shop limited-time offers picked for you before they are gone.",          "bodyLength": 428,          "screenshotUrl": "https://cdn.example.com/emails/123.png"        },        "shop": {          "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",          "domain": "example.com",          "name": "Example Shop"        }      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
emailId*number

Public email identifier used by search/get_email_html.

folderId?|

Favorite emails folder id (board id, or migrated V2 folder UUID). Null or omitted saves the email in the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/emails" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "emailId": 7298813  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",    "scope": "workspace",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",      "name": "Lifecycle Emails",      "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"    },    "email": {      "id": 123456,      "sentAt": "2026-04-18T12:30:00.000Z",      "campaignType": "Newsletter",      "classification": {        "promotionType": "Discount %",        "promotionTypeId": 1,        "category": "Promotional Campaign",        "categoryId": 4,        "event": {          "name": "Black Friday",          "id": 1,          "category": "Commercial Events"        }      },      "content": {        "subject": "Up to 30% off this weekend",        "preheader": "Limited-time offers picked for you.",        "bodyPreview": "Shop limited-time offers picked for you before they are gone.",        "bodyLength": 428,        "screenshotUrl": "https://cdn.example.com/emails/123.png"      },      "shop": {        "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",        "domain": "example.com",        "name": "Example Shop"      }    }  },  "created": true}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Favorite emails folder id (board id, or migrated V2 folder UUID). Null moves the saved email to the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/emails/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_item_f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",    "scope": "workspace",    "savedAt": "2026-04-20T10:00:00.000Z",    "folder": {      "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",      "name": "Lifecycle Emails",      "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"    },    "email": {      "id": 123456,      "sentAt": "2026-04-18T12:30:00.000Z",      "campaignType": "Newsletter",      "classification": {        "promotionType": "Discount %",        "promotionTypeId": 1,        "category": "Promotional Campaign",        "categoryId": 4,        "event": {          "name": "Black Friday",          "id": 1,          "category": "Commercial Events"        }      },      "content": {        "subject": "Up to 30% off this weekend",        "preheader": "Limited-time offers picked for you.",        "bodyPreview": "Shop limited-time offers picked for you before they are gone.",        "bodyLength": 428,        "screenshotUrl": "https://cdn.example.com/emails/123.png"      },      "shop": {        "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",        "domain": "example.com",        "name": "Example Shop"      }    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

favoriteId*string

Saved favorite id, which is the board item id.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/emails/saved/board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "emailId": 7298813,    "scope": "workspace",    "folderId": "0e91fbef-3d02-44d8-b024-3bda62fb050c",    "savedFavoriteId": "f3d7c2da-e64c-42c3-a0b1-ef1a4633592d"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

page?integer
limit?integer

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/favorites/emails/folders?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",      "name": "Lifecycle Emails",      "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 130,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string
name*string
parentId?|

Parent folder id (board id, or migrated V2 folder UUID). Null or omitted creates a root folder.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/favorites/emails/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Lifecycle Emails"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",    "name": "Lifecycle Emails",    "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folders*array<>

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/emails/folders/reorder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "folders": [      {        "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",        "order": 1      }    ]  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "reordered": true,    "scope": "workspace",    "folders": [      {        "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",        "name": "Lifecycle Emails",        "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"      }    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

visibility*string

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.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/emails/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",    "name": "Lifecycle Emails",    "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string
parentId?|

Parent folder id (board id, or migrated V2 folder UUID). Use null to make it a root folder; omit to keep the current parent.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/favorites/emails/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "board_0e91fbef-3d02-44d8-b024-3bda62fb050c",    "name": "Lifecycle Emails",    "parentId": "board_4b84a8f9-44df-4a18-9f08-66e6db6403da"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*string

Folder id: a board id, or the UUID of a V2 folder migrated to a board.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string
targetFolderId?|null

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/emails/folders/board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "mode": "move_items_to_root"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "deleted": true,    "folderId": "0e91fbef-3d02-44d8-b024-3bda62fb050c",    "scope": "workspace",    "mode": "delete_items",    "targetFolderId": "string",    "deletedFolderIds": [      "string"    ],    "affectedFavoriteIds": [      "string"    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

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.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

emailId*integer

Public email identifier. To delete a saved favorite row by its saved favorite id, use DELETE /v1/favorites/emails/saved/:favoriteId.

Query Parameters

scope*string

Favorites scope. Use personal only with a delegated_user credential. full_access credentials receive 403 for personal scope.

folderId?string

Favorite emails folder id (board id, or migrated V2 folder UUID). Omit to remove from the scope's "Unsorted" board.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/favorites/emails/1?scope=workspace"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "removed": true,    "emailId": 7298813,    "scope": "workspace",    "folderId": "0e91fbef-3d02-44d8-b024-3bda62fb050c",    "savedFavoriteId": "f3d7c2da-e64c-42c3-a0b1-ef1a4633592d"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}