tools/list for the current set rather than hard-coding it.
Inputs every tool shares
| Input | Rule |
|---|---|
workspace_id | Leave out with one workspace. With several, pass the id from list_workspaces. |
target.platform | meta, tiktok or google |
target.account_id | From list_ad_accounts: Meta act_…, the TikTok advertiser id, or the 10-digit Google Ads customer id |
confirm_token | Leave out to preview. Pass the token from a ready preview after the person’s yes. Valid 30 minutes, once. |
operation_id | Your own id for one intended write. Reuse it on retries, so a retry returns the first result. |
50 means 50.00.
Setup and reads
All needdatalyr:read only.
| Tool | Returns | Key inputs |
|---|---|---|
list_ad_accounts | The selected ad account per platform, can_publish with a reason and an action (reconnect, connect, turn_on_in_settings), and live_enabled | platform |
get_ad_publish_settings | Notifications, the rejected-ads pause, the domain rule, every enhancement default, and this connection’s level | |
list_ad_identities | Facebook Pages and Instagram accounts, or TikTok accounts and custom identities | platform, account_id |
list_ad_campaigns | Campaigns with objective, status, budget and can_add_ad_sets | platform, account_id, status |
list_ad_targets | Campaigns and their ad sets or ad groups, each with can_add_ads and blocked_reason | platform, account_id, campaign_id |
get_ad_requirements | What a new ad in one ad set needs: formats, text limits, file shapes, identities, enhancements, tracking, and what only you can answer | platform, account_id, container_id, format |
list_ad_pixels | Meta pixels with when each last fired, TikTok pixels, or Google conversion actions | platform, account_id |
list_ad_audiences | Custom and lookalike audiences, with size and readiness | platform, account_id |
search_targeting | Targeting ids. Meta: interest, behavior, location, zip, language. TikTok: location, interest, language. Google: location, language. | platform, account_id, type, q, objective (TikTok locations) |
list_ad_apps | Apps the account can advertise, for app installs. Meta and TikTok. | platform, account_id |
list_ad_lead_forms | A Page’s instant forms. Meta only. | account_id, page_id |
get_ad_objects | Status, delivery, budget and today’s spend for up to 50 objects, and created_by_agents | platform, account_id, ids |
get_ad_status | One request by operation_id: its status, each ad’s review state and Ads Manager link, or each change | operation_id |
list_ad_activity | The activity log, newest first | platform, limit (1–200, default 50), before |
Files
| Tool | Does | Key inputs | Level |
|---|---|---|---|
list_ad_assets | Lists the file library, newest first, with real size and shape | kind, limit, before | Read-only |
get_ad_asset | One file’s status: pending, processing, ready or failed | asset_id | Read-only |
import_ad_assets | Imports 1–20 files from links or ChatGPT attachments | urls, files | Create paused |
create_asset_upload | Returns an upload URL and headers for one local file | content_type, bytes, filename | Create paused |
finish_asset_upload | Checks an uploaded file and returns the asset | asset_id | Create paused |
Create
Each is a preview first, then the same call withconfirm_token. Everything is created paused.
| Tool | Creates | Key inputs |
|---|---|---|
create_campaign | One campaign | target, campaign: objective (Meta, TikTok) or type: "search" (Google), budget, name, spend_cap (Meta), bidding, locations, languages, search_partners (Google) |
create_ad_set | One ad set (Meta) or ad group (TikTok, Google) | target.campaign_id. ad_set: budget, bid, goal, targeting, placements, start_time, end_time. Google uses ad_group: keywords, negative_keywords, default_cpc. |
create_ad | 1–50 ads in one ad set or ad group | target.container_id, ads |
The ad object
| Field | Holds |
|---|---|
format | single_image, single_video, carousel, multi_asset, search_text, existing_post or video_responsive, one the ad set allows |
name | Optional. The default is headline · format · date. |
identity | Meta page_id and instagram_user_id. TikTok tiktok_identity_id. Google business_name and logo_asset_id. |
media | Up to 60 of { asset_id, role, card }. role is inferred from the file’s shape when left out. |
cards | Carousel cards: headline, description, url, cta |
text | primary, headlines (with optional pin), long_headlines, descriptions (with optional pin), display_paths |
cta | A value like SHOP_NOW, or a platform value like meta:GET_DETAILS |
destination | url, and optional display_url and deeplink |
tracking | preset: datalyr (default) or none. Optional extra utm values. |
existing_post | post_id, and on Meta source: facebook or instagram |
enhancements | { key: "on" or "off" } for this ad. Left-out keys use the workspace default, else off. |
platform_options | Meta lead_form_id. TikTok music_id, dark_post, allow_duet_stitch. Google youtube_video_ids and display colors. |
{
"target": { "platform": "meta", "account_id": "act_123", "container_id": "120210000000000001" },
"operation_id": "spring-sale-ads-1",
"ads": [
{
"format": "single_image",
"media": [{ "asset_id": "4f6c2a3e-0000-4000-8000-000000000001" }],
"text": { "primary": ["20% off this week."], "headlines": [{ "text": "Spring sale" }] },
"cta": "SHOP_NOW",
"destination": { "url": "https://shop.example.com/spring" }
}
]
}
Change
Each is a preview first, thenconfirm_token. Each takes up to 50 objects in one ad account.
| Tool | Does | Key inputs | Level for agent-made objects |
|---|---|---|---|
activate_ad_objects | Turns campaigns, ad sets and ads on, the campaign last | target, objects: [{ id }] | Publish live |
pause_ad_objects | Pauses them, the campaign first | target, objects | Create paused |
set_ad_budget | Changes daily or lifetime budgets | target, changes: [{ id, daily }] or [{ id, lifetime }] | Create paused to lower, Publish live to raise |
update_ad_content | New content for one Meta ad | target, ad_id, ad | Create paused for a paused ad, Publish live for a running ad |
archive_ad_objects | Archives agent-made Meta objects and everything under them | target, objects | Create paused |
delete_ad_objects | Deletes agent-made Meta or TikTok objects and everything under them | target, objects | Publish live, owner only |
Stop and settings
| Tool | Does | Key inputs | Level |
|---|---|---|---|
stop_agent_ads | Switches live ads off and pauses everything agents turned on. No preview. | None | Create paused |
update_ad_publish_settings | Changes enhancement defaults and the two email settings. Platforms, live ads, spend limits, the domain rule and the rejected-ads pause stay with people in Settings. | enhancements, notifications: { digest, alarms } | Create paused |
Use the HTTP API
Scripts reach the same tools athttps://api.datalyr.com/v1/ad-publish with a named API
key that carries an ads level. See API keys.
| Rule | Detail |
|---|---|
| Body | The tool’s fields at the top level, without workspace_id and operation_id |
operation_id | Send it as the Idempotency-Key header |
| Preview | A request without confirm_token is a preview, as over MCP |
| Turning on, raising, deleting | Always an approval link for the owner from a key |
| Route | Tool |
|---|---|
GET /ad-publish/accounts, /identities, /targets, /requirements, /campaigns, /pixels, /audiences, /targeting, /apps, /lead-forms, /objects | The matching read tools, with their inputs as query parameters. ids is comma-separated. |
GET /ad-publish/settings, /activity | get_ad_publish_settings, list_ad_activity |
GET /ad-publish/assets, /assets/{asset_id} | list_ad_assets, get_ad_asset |
GET /ad-publish/operations/{operation_id} | get_ad_status |
POST /ad-publish/assets/uploads, /assets/{asset_id}/finish, /assets/import | create_asset_upload, finish_asset_upload, import_ad_assets |
POST /ad-publish/campaigns, /ad-sets, /ads | create_campaign, create_ad_set, create_ad |
POST /ad-publish/activate, /pause, /budgets, /edit, /archive, /delete | The change tools, in that order |
POST /ad-publish/stop | stop_agent_ads |
PATCH /ad-publish/settings | update_ad_publish_settings, with the fields under settings |
curl -X POST https://api.datalyr.com/v1/ad-publish/pause \
--header "Authorization: Bearer dk_agent_YOUR_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: pause-spring-1" \
--data '{"target":{"platform":"meta","account_id":"act_123"},"objects":[{"id":"120210000000000001"}]}'
Next
- How agents publish: preview statuses and results.
- Access levels and approvals: what each level allows.
- Connect Claude or Codex: the MCP server and its other tools.