Favorites

List favorite ads

Returns the authenticated workspace or delegated-user favorite ads. The response embeds the canonical public ad summary when the backing favorite resolves to a public-supported ad.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

folderId?string

Public ads folder identifier. This value matches the ads folder UUID; numeric folder IDs are internal.

Formatuuid

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/ads?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": 123,
      "scope": "workspace",
      "savedAt": "2026-04-20T10:00:00.000Z",
      "folder": {
        "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
        "name": "Winning Creatives",
        "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
      },
      "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": "US",
          "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"
          ]
        }
      ]
    }
  }
}

Add a favorite ad

Saves an ad to the requested workspace or delegated-user favorites scope. Existing favorites are returned idempotently without creating an audit mutation event.

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

Value in"workspace" | "personal"

adId*string

Composite public ad identifier, for example facebook_123 or tiktok_123.

folderId?|

Public favorite ads folder UUID. Null or omitted saves the ad at root.

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/ads" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "adId": "facebook_1234567890"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 123,
    "scope": "workspace",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
      "name": "Winning Creatives",
      "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
    },
    "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": "US",
        "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"
          ]
        }
      ]
    }
  }
}

Move a saved favorite ad

Moves one saved favorite ad row by its current saved favorite id. Ads currently expose favorite_ads.id as the saved-row identifier in v1 reads; it is numeric and not a new opaque UUID.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*integer

Saved favorite ad row identifier from the favorite ads list response. Numeric favorite_ads IDs are the current v1 identifier for ads saved rows.

Range1 <= value

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Public favorite ads folder UUID. Null moves the saved ad to root.

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/ads/saved/1/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 123,
    "scope": "workspace",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
      "name": "Winning Creatives",
      "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
    },
    "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": "US",
        "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"
          ]
        }
      ]
    }
  }
}

Delete a saved favorite ad

Deletes one saved favorite ad row by its current saved favorite id. Ads currently expose favorite_ads.id as the saved-row identifier in v1 reads; it is numeric and not a new opaque UUID.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*integer

Saved favorite ad row identifier from the favorite ads list response. Numeric favorite_ads IDs are the current v1 identifier for ads saved rows.

Range1 <= value

Query Parameters

scope*string

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

Value in"workspace" | "personal"

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/ads/saved/1?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "removed": true,
    "adId": "facebook_1234567890",
    "scope": "workspace",
    "folderId": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa"
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Remove a favorite ad

Removes an ad from the requested workspace or delegated-user favorites scope and writes a before/null audit mutation event.

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.

Value in"workspace" | "personal"

folderId?string

Public ads folder identifier. This value matches the ads folder UUID; numeric folder IDs are internal.

Formatuuid

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/ads/string?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "removed": true,
    "adId": "facebook_1234567890",
    "scope": "workspace",
    "folderId": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa"
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

List favorite ad folders

Returns the ads folders available in the requested favorites scope. Ads folders stay separate from shops folders in v1.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

parentId?string

Public parent folder UUID. Returns only direct children of this folder. Cannot be combined with rootOnly=true.

Formatuuid

rootOnly?boolean

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

Defaultfalse

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/ads/folders?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
      "name": "Winning Creatives",
      "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
    }
  ],
  "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"
          ]
        }
      ]
    }
  }
}

Create a favorite ad folder

Creates a root folder or subfolder in the requested workspace or delegated-user favorite ads scope and writes a null/after audit mutation event.

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

Value in"workspace" | "personal"

name*string

parentId?|

Public parent folder UUID. Null or omitted creates a root folder.

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/ads/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Winning Creatives"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
    "name": "Winning Creatives",
    "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Reorder favorite ad folders

Updates sibling ordering values for favorite ad folders in the requested scope. Static route is declared before :folderId routes to avoid route shadowing.

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.

Value in"workspace" | "personal"

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.

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/ads/folders/reorder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "folders": [      {        "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",        "order": 1      }    ]  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "reordered": true,
    "scope": "workspace",
    "folders": [
      {
        "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
        "name": "Winning Creatives",
        "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
      }
    ]
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Creates or returns the existing TrendTrack public webapp share URL for a favorite ad folder. Workspace-scoped folders require workspace writer authorization; personal folders require delegated owner access.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite ads folder UUID in the current scope.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/ads/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08/share?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "folderId": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
    "folder": {
      "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
      "name": "Winning Creatives",
      "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
    },
    "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
    "slug": "winning-creatives-9a8b7c",
    "shareUrl": "https://app.trendtrack.io/share/ads/winning-creatives-9a8b7c",
    "sharePath": "/share/ads/winning-creatives-9a8b7c",
    "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"
          ]
        }
      ]
    }
  }
}

Set favorite ad folder visibility

Switches a root favorite ad folder tree between private delegated-user scope and organization workspace scope. Workspace-scoped writes require a workspace writer; private conversion requires delegated ownership of every contained folder and saved ad.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite ads folder UUID in the current scope.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

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.

Value in"private" | "organization"

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/ads/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
    "name": "Winning Creatives",
    "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Rename or move a favorite ad folder

Renames and/or moves a favorite ad folder. parentId null moves the folder to root; parentId omitted keeps the current parent.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite ads folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

parentId?|

Public parent folder UUID. Use null to move the folder to root; omit to keep the current parent.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/ads/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
    "name": "Winning Creatives",
    "parentId": "f2c0dc30-95bf-4455-bb43-48d5f6e08f30"
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Delete a favorite ad folder

Deletes a favorite ad folder tree with explicit contained-ad handling: delete_items, move_items_to_root, or move_items_to_folder. Cross-scope target folders are rejected by scoped lookup.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite ads folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

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.

Value in"delete_items" | "move_items_to_root" | "move_items_to_folder"

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`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/ads/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "mode": "move_items_to_root"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "deleted": true,
    "folderId": "b8fd7b35-9231-4ed0-9d76-2cb27ee7f3aa",
    "scope": "workspace",
    "mode": "delete_items",
    "targetFolderId": "string",
    "deletedFolderIds": [
      "string"
    ],
    "affectedFavoriteIds": [
      0
    ]
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

List favorite shops

Returns the authenticated workspace or delegated-user favorite shops. Each item embeds the canonical public shop summary shape.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

folderId?string

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

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/shops?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "8f92ad4a-61e8-4519-a182-4f8e24db0e52",
      "scope": "personal",
      "savedAt": "2026-04-20T10:00:00.000Z",
      "folder": {
        "id": "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
            }
          ]
        },
        "advertising": {
          "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"
          }
        ]
      }
    }
  ],
  "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"
          ]
        }
      ]
    }
  }
}

Add a favorite shop

Saves a website/shop to the requested workspace or delegated-user favorites scope. The server resolves trusted domain and shop metadata from websiteId; clients cannot supply authoritative domain state.

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

Value in"workspace" | "personal"

websiteId*string

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

folderId?|

Public favorite shops folder UUID. Null or omitted saves the shop at root.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/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": "8f92ad4a-61e8-4519-a182-4f8e24db0e52",
    "scope": "personal",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "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
          }
        ]
      },
      "advertising": {
        "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"
        }
      ]
    }
  },
  "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"
          ]
        }
      ]
    }
  }
}

Move a saved favorite shop

Moves one saved favorite shop row by favorite_websites.id. Shop folders are flat; folderId null moves the saved shop to root and cross-scope moves are rejected by scoped lookup.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*string

Saved favorite shop row identifier from favorite_websites.id.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Public favorite shops folder UUID. Null moves the saved shop to root.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/shops/saved/497f6eca-6276-4993-bfeb-53cbbbba6f08/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "8f92ad4a-61e8-4519-a182-4f8e24db0e52",
    "scope": "personal",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "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
          }
        ]
      },
      "advertising": {
        "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"
        }
      ]
    }
  }
}

{
  "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"
          ]
        }
      ]
    }
  }
}

Delete a saved favorite shop

Deletes one saved favorite shop row by favorite_websites.id in the requested scope.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*string

Saved favorite shop row identifier from favorite_websites.id.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/shops/saved/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": "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"
          ]
        }
      ]
    }
  }
}

Remove a favorite shop by website id

Removes a website/shop favorite from the requested scope and optional flat folder. To remove a specific saved row, prefer DELETE /v1/favorites/shops/saved/:favoriteId.

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.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

folderId?string

Public favorite shops folder UUID. Omit to remove from root.

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/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": "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"
          ]
        }
      ]
    }
  }
}

List favorite shop folders

Returns the shops folders available in the requested favorites scope. Shops folders stay separate from ads folders in v1.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/shops/folders?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "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"
          ]
        }
      ]
    }
  }
}

Create a favorite shop folder

Creates a flat favorite shops folder in the requested workspace or delegated-user scope. Hierarchy is not supported for shop folders in this API version.

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

Value in"workspace" | "personal"

name*string

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/shops/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Competitors"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "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"
          ]
        }
      ]
    }
  }
}

Set favorite shop folder visibility

Switches a flat favorite shop folder between private delegated-user scope and organization workspace scope. Private conversion is denied when the folder contains other users’ saved shops.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite shops folder UUID in the current scope.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

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.

Value in"private" | "organization"

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/shops/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "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"
          ]
        }
      ]
    }
  }
}

Rename a favorite shop folder

Renames a flat favorite shops folder. Parent moves and hierarchy are not supported for shop folders in this API version.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite shops folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/shops/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "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"
          ]
        }
      ]
    }
  }
}

Delete a favorite shop folder

Deletes a flat favorite shops folder with explicit contained-shop handling: delete_items, move_items_to_root, or move_items_to_folder. Hierarchy and reorder are not supported for shop folders.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite shops folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

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.

Value in"delete_items" | "move_items_to_root" | "move_items_to_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`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/shops/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "mode": "move_items_to_root"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "deleted": true,
    "folderId": "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"
          ]
        }
      ]
    }
  }
}

List favorite emails

Returns saved email favorites. The email payload is null when backing email content is unavailable, but the saved row is retained.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

folderId?string

Public email folder UUID. Numeric folder IDs are internal and never accepted by the Public API.

Formatuuid

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/emails?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",
      "scope": "workspace",
      "savedAt": "2026-04-20T10:00:00.000Z",
      "folder": {
        "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
        "name": "Lifecycle Emails",
        "parentId": "4b84a8f9-44df-4a18-9f08-66e6db6403da"
      },
      "email": {
        "id": 123456,
        "sentAt": "2026-04-18T12:30:00.000Z",
        "campaignType": "Newsletter",
        "classification": {
          "promotionType": "Discount",
          "promotionTypeId": 4,
          "category": "Promotional",
          "categoryId": 7,
          "event": {
            "name": "Black Friday",
            "id": 12,
            "category": "Sales"
          }
        },
        "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"
          ]
        }
      ]
    }
  }
}

Add or update a favorite email

Adds or upserts a saved email favorite in the requested scope. Existing saved rows are updated only within the same scope.

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

Value in"workspace" | "personal"

emailId*number

Public email identifier used by search/get_email_html.

folderId?|

Public favorite email folder UUID. Null or omitted saves the email at root.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/emails" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "emailId": 7298813  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",
    "scope": "workspace",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
      "name": "Lifecycle Emails",
      "parentId": "4b84a8f9-44df-4a18-9f08-66e6db6403da"
    },
    "email": {
      "id": 123456,
      "sentAt": "2026-04-18T12:30:00.000Z",
      "campaignType": "Newsletter",
      "classification": {
        "promotionType": "Discount",
        "promotionTypeId": 4,
        "category": "Promotional",
        "categoryId": 7,
        "event": {
          "name": "Black Friday",
          "id": 12,
          "category": "Sales"
        }
      },
      "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"
          ]
        }
      ]
    }
  }
}

Move a saved favorite email

Moves one saved favorite email by favorite_emails.uuid. Numeric saved-row IDs are internal.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*string

Public saved favorite email UUID from favorite_emails.uuid.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folderId?|

Public favorite email folder UUID. Null moves the saved email to root.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/emails/saved/497f6eca-6276-4993-bfeb-53cbbbba6f08/folder?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "f3d7c2da-e64c-42c3-a0b1-ef1a4633592d",
    "scope": "workspace",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
      "name": "Lifecycle Emails",
      "parentId": "4b84a8f9-44df-4a18-9f08-66e6db6403da"
    },
    "email": {
      "id": 123456,
      "sentAt": "2026-04-18T12:30:00.000Z",
      "campaignType": "Newsletter",
      "classification": {
        "promotionType": "Discount",
        "promotionTypeId": 4,
        "category": "Promotional",
        "categoryId": 7,
        "event": {
          "name": "Black Friday",
          "id": 12,
          "category": "Sales"
        }
      },
      "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"
          ]
        }
      ]
    }
  }
}

Delete a saved favorite email

Deletes one saved favorite email row by favorite_emails.uuid.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

favoriteId*string

Public saved favorite email UUID from favorite_emails.uuid.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/emails/saved/497f6eca-6276-4993-bfeb-53cbbbba6f08?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"
          ]
        }
      ]
    }
  }
}

List favorite email folders

Returns favorite email folders in the requested scope. Folder IDs are public UUIDs.

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.

Value in"workspace" | "personal"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/favorites/emails/folders?scope=workspace"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
      "name": "Lifecycle Emails",
      "parentId": "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"
          ]
        }
      ]
    }
  }
}

Create a favorite email folder

Creates a root or nested favorite email folder using public UUID folder identifiers.

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

Value in"workspace" | "personal"

name*string

parentId?|

Public parent email folder UUID. Null or omitted creates a root folder.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/favorites/emails/folders" \  -H "Content-Type: application/json" \  -d '{    "scope": "workspace",    "name": "Lifecycle Emails"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
    "name": "Lifecycle Emails",
    "parentId": "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"
          ]
        }
      ]
    }
  }
}

Reorder favorite email folders

Updates sibling order values for favorite email folders in the requested scope. Static route is declared before :folderId routes to avoid route shadowing.

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.

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

folders*array<>

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/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": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
        "name": "Lifecycle Emails",
        "parentId": "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"
          ]
        }
      ]
    }
  }
}

Set favorite email folder visibility

Switches a root favorite email folder tree between delegated-user private scope and workspace organization scope. Workspace-scoped writes require a workspace writer; private conversion requires delegated ownership of every contained folder and saved email.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite emails folder UUID in the current scope.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

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.

Value in"private" | "organization"

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/emails/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08/visibility?scope=workspace" \  -H "Content-Type: application/json" \  -d '{    "visibility": "organization"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
    "name": "Lifecycle Emails",
    "parentId": "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"
          ]
        }
      ]
    }
  }
}

Rename or move a favorite email folder

Renames and/or moves a favorite email folder. parentId null moves the folder to root.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite emails folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

parentId?|

Public parent email folder UUID. Use null to move to root; omit to keep the current parent.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/favorites/emails/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?scope=workspace" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "0e91fbef-3d02-44d8-b024-3bda62fb050c",
    "name": "Lifecycle Emails",
    "parentId": "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"
          ]
        }
      ]
    }
  }
}

Delete a favorite email folder

Deletes a favorite email folder tree with explicit contained-email handling: delete_items, move_items_to_root, or move_items_to_folder. Cross-scope target folders are rejected by scoped lookup.

Authorization

publicApiBearer

AuthorizationBearer <token>

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

In: header

Path Parameters

folderId*string

Public favorite emails folder UUID.

Formatuuid

Query Parameters

scope*string

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

Value in"workspace" | "personal"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Value in"delete_items" | "move_items_to_root" | "move_items_to_folder"

targetFolderId?|null

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/favorites/emails/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08?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"
          ]
        }
      ]
    }
  }
}

Remove a favorite email by email id

Removes a saved favorite email from the requested scope and optional folder. To remove a specific saved row, prefer DELETE /v1/favorites/emails/saved/:favoriteId.

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 favorite_emails.uuid, use DELETE /v1/favorites/emails/saved/:favoriteId.

Range1 <= value

Query Parameters

scope*string

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

Value in"workspace" | "personal"

folderId?string

Public email folder UUID. Numeric folder IDs are internal and never accepted by the Public API.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/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"
          ]
        }
      ]
    }
  }
}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`