Docs
Ctrl+K Rechercher Alt+[Alt+] Guides
Obtenir une clé API

API

Saved ads

Manage saved-ad folders and boards, add or remove ads, and save creatives programmatically. Mirrors the dashboard Saved Ads library. Each call costs 1 API credit with your API key.

Platforms supported when saving: facebook, facebook_post, pinterest, tiktok, google.

Quick save

PUBLICATION/api/v1/saved-ads/save

Save an ad to the default board or a specific board.

Send Clé X-API on every request.

Body parameters

  • ad_idstringrequired
  • platformstring
    Default: facebook
  • board_idstring

    Defaults to your default board when omitted.

Demande
curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/saved-ads/save" \
  -d '{"ad_id":"string","platform":"facebook","board_id":"string"}'
const res = await fetch(`${ORIGIN}/api/v1/saved-ads/save`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "ad_id": "string",
      "platform": "facebook",
      "board_id": "string"
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/saved-ads/save",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "ad_id": "string",
        "platform": "facebook",
        "board_id": "string"
    },
)
data = res.json()
Response
{
    "success": true,
    "ad_id": "1284756102394857",
    "platform": "facebook",
    "board_id": 42,
    "already_saved": false,
    "message": "Ad saved to your saved ads board."
}
{
    "success": false,
    "error": "invalid_argument",
    "message": "ad_id is required"
}
{
    "success": false,
    "error": "Unauthorized"
}

Every platform is board-backed, TikTok included, so board_id is honoured across the board. Already-saved returns "message": "Ad is already saved on this board." avec already_saved: true.

TikTok saves are additionally mirrored into the legacy per-user TikTok list that drives the filled heart and the "saved only" toggle on the /tiktok-ads grid, and unsaving clears both. TikTok ads saved before this became board-backed still show under "All Saved Ads" but sit on no board until they are saved again.

Folders & boards

Method Chemin Objectif
OBTENIR /api/v1/saved-ads/folders List folders (bare array)
OBTENIR /api/v1/saved-ads/boards List boards (bare array)
OBTENIR /api/v1/saved-ads/folders-with-boards Nested tree; optional ad_id + platform marks boards containing the ad
PUBLICATION /api/v1/saved-ads/create-folder Create folder (nom) → { success, folder_id, name }
PUBLICATION /api/v1/saved-ads/create-board Create board (folder_id, nom) → { success, board_id, name, folder_id }
PUBLICATION /api/v1/saved-ads/rename-folder Rename folder (folder_id, nom) → { success, folder_id, new_name }
PUBLICATION /api/v1/saved-ads/rename-board Rename board (board_id, nom) → { success, board_id, new_name }
PUBLICATION /api/v1/saved-ads/delete-folder Delete folder (folder_id)
PUBLICATION /api/v1/saved-ads/delete-board Delete board (board_id)
PUBLICATION /api/v1/saved-ads/add-ad Add ad to board (ad_id, board_id, optional platform)
PUBLICATION /api/v1/saved-ads/remove-ad Remove ad from board (ad_id, board_id, optional platform)

JSON body or form fields; GET query params are merged where applicable. Validation failures often return HTTP 200 avec { "success": false, "message": "…" } while still logged in.

OBTENIR/api/v1/saved-ads/folders-with-boards

Nested folders and boards; optional ad membership flags.

Send Clé X-API on every request.

Query parameters

  • ad_idstring
  • platformstring
    Default: facebook
Demande
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/saved-ads/folders-with-boards?ad_id=string&platform=facebook"
const res = await fetch(`${ORIGIN}/api/v1/saved-ads/folders-with-boards?ad_id=string&platform=facebook`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();
import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/saved-ads/folders-with-boards?ad_id=string&platform=facebook",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()
Response
[
    {
        "id": 3,
        "name": "Competitors",
        "created_at": null,
        "boards": [
            {
                "id": 42,
                "name": "Winning hooks",
                "ads_count": 18,
                "contains_ad": true
            }
        ]
    }
]
PUBLICATION/api/v1/saved-ads/create-folder

Create a saved-ads folder.

Send Clé X-API on every request.

Body parameters

  • nomstringrequired
Demande
curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/saved-ads/create-folder" \
  -d '{"name":"string"}'
const res = await fetch(`${ORIGIN}/api/v1/saved-ads/create-folder`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string"
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/saved-ads/create-folder",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "name": "string"
    },
)
data = res.json()
Response
{
    "success": true,
    "folder_id": 9,
    "name": "Competitors"
}
{
    "success": false,
    "message": "Folder name is required"
}
PUBLICATION/api/v1/saved-ads/add-ad

Add an ad to a board.

Send Clé X-API on every request.

Body parameters

  • ad_idstringrequired
  • board_idstringrequired
  • platformstring
    Default: facebook
Demande
curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/saved-ads/add-ad" \
  -d '{"ad_id":"string","board_id":"string","platform":"facebook"}'
const res = await fetch(`${ORIGIN}/api/v1/saved-ads/add-ad`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "ad_id": "string",
      "board_id": "string",
      "platform": "facebook"
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/saved-ads/add-ad",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "ad_id": "string",
        "board_id": "string",
        "platform": "facebook"
    },
)
data = res.json()
Response
{
    "success": true,
    "ad_id": "1284756102394857",
    "board_id": 42,
    "platform": "facebook"
}
{
    "success": false,
    "message": "Board not found or not owned by this user"
}

GET /folders et GET /boards return bare JSON arrays of folder/board rows (no { success } wrapper).

curl -sS -X POST -H "X-API-Key: $WH_API_KEY" -H "Content-Type: application/json" \
  -d '{"ad_id":"1284756102394857","platform":"facebook"}' \
  "{origin}/api/v1/saved-ads/save"

Session equivalents live under /api/savedads/* for browser use.