Update ad
curl --request PUT \
--url https://api.aisa.one/apis/v1/ads/{adId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api.aisa.one/apis/v1/ads/{adId}"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.aisa.one/apis/v1/ads/{adId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/{adId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/ads/{adId}"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.aisa.one/apis/v1/ads/{adId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/{adId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"ad": {
"_id": "<string>",
"adSetName": "<string>",
"adType": "boost",
"bidAmount": 123,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"budget": {
"amount": 123,
"daily": 123,
"lifetime": 123,
"pacing": "<string>",
"type": "daily"
},
"campaignName": "<string>",
"configuredStatus": "<string>",
"costType": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"creative": {
"adFormat": "<string>",
"assetGroup": {
"businessName": "<string>",
"descriptions": [
"<string>"
],
"finalUrl": "<string>",
"headlines": [
"<string>"
],
"images": {},
"longHeadline": "<string>",
"name": "<string>",
"youtubeVideoId": "<string>"
},
"assetGroupResourceName": "<string>",
"assetResourceName": "<string>",
"assets": {
"marketingImages": [
{}
],
"squareMarketingImages": [
{}
]
},
"bodies": [
"<string>"
],
"body": "<string>",
"callToAction": "<string>",
"carouselCards": [
{}
],
"catalog": {
"format": "single_image",
"formatTransformationSpec": [
{}
],
"productSetId": "<string>"
},
"creativeFeatures": {},
"creativeId": "<string>",
"description": "<string>",
"descriptions": [
"<string>"
],
"effectiveInstagramMediaId": "<string>",
"effectiveObjectStoryId": "<string>",
"finalUrls": [
"<string>"
],
"googleDescription": "<string>",
"googleHeadline": "<string>",
"headline": "<string>",
"headlines": [
"<string>"
],
"imageHash": "<string>",
"imageUrl": "<string>",
"instagramPermalinkUrl": "<string>",
"instagramUserId": "<string>",
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {},
"videoId": "<string>"
},
"isServing": true,
"leadGenFormId": "<string>",
"linkUrl": "<string>",
"mediaUrls": [
"<string>"
],
"objectStoryId": "<string>",
"objectType": "<string>",
"pageId": "<string>",
"pinterestDescription": "<string>",
"pinterestImageUrl": "<string>",
"pinterestTitle": "<string>",
"servingHoldReasons": [
"<string>"
],
"thumbnailUrl": "<string>",
"urlTags": "<string>",
"videoId": "<string>",
"videoUrl": "<string>",
"whatsappPhoneNumber": "<string>",
"youtubeVideoIds": [
"<string>"
]
},
"creativeType": "carousel",
"goal": "engagement",
"isExternal": true,
"metrics": {
"actionValues": {},
"actions": {},
"allConversions": 123,
"clicks": 123,
"conversions": 123,
"costPerAction": {},
"costPerConversion": 123,
"costPerThruplay": 123,
"cpc": 123,
"cpm": 123,
"ctr": 123,
"engagement": 123,
"engagementBreakdown": {
"comments": 123,
"linkClicks": 123,
"pageEngagement": 123,
"pageLikes": 123,
"postEngagement": 123,
"reactions": 123,
"saves": 123,
"shares": 123,
"videoViews": 123
},
"funnel": {
"appInstalls": 123,
"cartAdds": 123,
"checkoutsInitiated": 123,
"contentViews": 123,
"landingPageViews": 123,
"leads": 123,
"messagingConversationsStarted": 123,
"messagingFirstReplies": 123,
"paymentInfoAdds": 123,
"purchases": 123,
"registrationsCompleted": 123,
"searches": 123,
"wishlistAdds": 123
},
"impressions": 123,
"inlineLinkClickCtr": 123,
"inlineLinkClicks": 123,
"lastSyncedAt": "2023-11-07T05:31:56Z",
"outboundClicks": 123,
"outboundClicksCtr": 123,
"purchaseValue": 123,
"reach": 123,
"roas": 123,
"spend": 123,
"uniqueClicks": 123,
"uniqueCtr": 123,
"video2SecWatchedActions": 123,
"video30SecWatchedActions": 123,
"video6SecFocusedViews": 123,
"video6SecWatchedActions": 123,
"videoAvgTimeWatchedActions": 123,
"videoP100WatchedActions": 123,
"videoP25WatchedActions": 123,
"videoP50WatchedActions": 123,
"videoP75WatchedActions": 123,
"videoP95WatchedActions": 123,
"videoPlayActions": 123,
"videoThruplayWatchedActions": 123
},
"name": "<string>",
"optimizationGoal": "<string>",
"platform": "facebook",
"platformAdAccountId": "<string>",
"platformAdAccountName": "<string>",
"platformAdId": "<string>",
"platformAdSetId": "<string>",
"platformCampaignId": "<string>",
"platformCreatedAt": "2023-11-07T05:31:56Z",
"platformObjective": "<string>",
"promotedObject": {
"application_id": "<string>",
"custom_event_type": "<string>",
"page_id": "<string>",
"pixel_id": "<string>",
"product_set_id": "<string>"
},
"rejectionReason": "<string>",
"reviewStatus": "in_review",
"roasAverageFloor": 123,
"schedule": {
"endDate": "2023-11-07T05:31:56Z",
"startDate": "2023-11-07T05:31:56Z"
},
"servingStatuses": [
"<string>"
],
"status": "active",
"synced": true,
"targeting": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"message": "<string>"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}AIsa Ads
Update ad
Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Changes an ad's budget, targeting or status. Changes an ad's status, budget, targeting or creative and applies the change on the platform. Patch one or more fields on an ad. Status, budget, targeting, and creative changes are propagated to the platform. ### Per-platform support Meta (Facebook + Instagram): all fields supported.
<!-- aisa-pricing:start -->
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.
<!-- aisa-pricing:end -->
PUT
https://api.aisa.one
/
apis
/
v1
/
ads
/
{adId}
Update ad
curl --request PUT \
--url https://api.aisa.one/apis/v1/ads/{adId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api.aisa.one/apis/v1/ads/{adId}"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.aisa.one/apis/v1/ads/{adId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/{adId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.aisa.one/apis/v1/ads/{adId}"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.aisa.one/apis/v1/ads/{adId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/{adId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"ad": {
"_id": "<string>",
"adSetName": "<string>",
"adType": "boost",
"bidAmount": 123,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"budget": {
"amount": 123,
"daily": 123,
"lifetime": 123,
"pacing": "<string>",
"type": "daily"
},
"campaignName": "<string>",
"configuredStatus": "<string>",
"costType": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"creative": {
"adFormat": "<string>",
"assetGroup": {
"businessName": "<string>",
"descriptions": [
"<string>"
],
"finalUrl": "<string>",
"headlines": [
"<string>"
],
"images": {},
"longHeadline": "<string>",
"name": "<string>",
"youtubeVideoId": "<string>"
},
"assetGroupResourceName": "<string>",
"assetResourceName": "<string>",
"assets": {
"marketingImages": [
{}
],
"squareMarketingImages": [
{}
]
},
"bodies": [
"<string>"
],
"body": "<string>",
"callToAction": "<string>",
"carouselCards": [
{}
],
"catalog": {
"format": "single_image",
"formatTransformationSpec": [
{}
],
"productSetId": "<string>"
},
"creativeFeatures": {},
"creativeId": "<string>",
"description": "<string>",
"descriptions": [
"<string>"
],
"effectiveInstagramMediaId": "<string>",
"effectiveObjectStoryId": "<string>",
"finalUrls": [
"<string>"
],
"googleDescription": "<string>",
"googleHeadline": "<string>",
"headline": "<string>",
"headlines": [
"<string>"
],
"imageHash": "<string>",
"imageUrl": "<string>",
"instagramPermalinkUrl": "<string>",
"instagramUserId": "<string>",
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {},
"videoId": "<string>"
},
"isServing": true,
"leadGenFormId": "<string>",
"linkUrl": "<string>",
"mediaUrls": [
"<string>"
],
"objectStoryId": "<string>",
"objectType": "<string>",
"pageId": "<string>",
"pinterestDescription": "<string>",
"pinterestImageUrl": "<string>",
"pinterestTitle": "<string>",
"servingHoldReasons": [
"<string>"
],
"thumbnailUrl": "<string>",
"urlTags": "<string>",
"videoId": "<string>",
"videoUrl": "<string>",
"whatsappPhoneNumber": "<string>",
"youtubeVideoIds": [
"<string>"
]
},
"creativeType": "carousel",
"goal": "engagement",
"isExternal": true,
"metrics": {
"actionValues": {},
"actions": {},
"allConversions": 123,
"clicks": 123,
"conversions": 123,
"costPerAction": {},
"costPerConversion": 123,
"costPerThruplay": 123,
"cpc": 123,
"cpm": 123,
"ctr": 123,
"engagement": 123,
"engagementBreakdown": {
"comments": 123,
"linkClicks": 123,
"pageEngagement": 123,
"pageLikes": 123,
"postEngagement": 123,
"reactions": 123,
"saves": 123,
"shares": 123,
"videoViews": 123
},
"funnel": {
"appInstalls": 123,
"cartAdds": 123,
"checkoutsInitiated": 123,
"contentViews": 123,
"landingPageViews": 123,
"leads": 123,
"messagingConversationsStarted": 123,
"messagingFirstReplies": 123,
"paymentInfoAdds": 123,
"purchases": 123,
"registrationsCompleted": 123,
"searches": 123,
"wishlistAdds": 123
},
"impressions": 123,
"inlineLinkClickCtr": 123,
"inlineLinkClicks": 123,
"lastSyncedAt": "2023-11-07T05:31:56Z",
"outboundClicks": 123,
"outboundClicksCtr": 123,
"purchaseValue": 123,
"reach": 123,
"roas": 123,
"spend": 123,
"uniqueClicks": 123,
"uniqueCtr": 123,
"video2SecWatchedActions": 123,
"video30SecWatchedActions": 123,
"video6SecFocusedViews": 123,
"video6SecWatchedActions": 123,
"videoAvgTimeWatchedActions": 123,
"videoP100WatchedActions": 123,
"videoP25WatchedActions": 123,
"videoP50WatchedActions": 123,
"videoP75WatchedActions": 123,
"videoP95WatchedActions": 123,
"videoPlayActions": 123,
"videoThruplayWatchedActions": 123
},
"name": "<string>",
"optimizationGoal": "<string>",
"platform": "facebook",
"platformAdAccountId": "<string>",
"platformAdAccountName": "<string>",
"platformAdId": "<string>",
"platformAdSetId": "<string>",
"platformCampaignId": "<string>",
"platformCreatedAt": "2023-11-07T05:31:56Z",
"platformObjective": "<string>",
"promotedObject": {
"application_id": "<string>",
"custom_event_type": "<string>",
"page_id": "<string>",
"pixel_id": "<string>",
"product_set_id": "<string>"
},
"rejectionReason": "<string>",
"reviewStatus": "in_review",
"roasAverageFloor": 123,
"schedule": {
"endDate": "2023-11-07T05:31:56Z",
"startDate": "2023-11-07T05:31:56Z"
},
"servingStatuses": [
"<string>"
],
"status": "active",
"synced": true,
"targeting": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"message": "<string>"
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}Request contract
- Method and path: PUT /apis/v1/ads/{adId}
- Availability: enabled
- Request URL template:
https://api.aisa.one/apis/v1/ads/{adId} - adId: path; required
- connectionId: query; required
- X-Aisa-Confirm: header; optional
- Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09
{
"operationId": "put_aisa_ads_apis_v1_ads_adid",
"method": "PUT",
"path": "/apis/v1/ads/{adId}",
"servers": [
{
"url": "https://api.aisa.one"
}
],
"parameters": [
{
"in": "path",
"name": "adId",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
"in": "query",
"name": "connectionId",
"required": true,
"schema": {
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
}
},
{
"description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.",
"in": "header",
"name": "X-Aisa-Confirm",
"required": false,
"schema": {
"enum": [
"spend"
],
"type": "string"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"connectionId": "adc_7f3k2m9q",
"descriptions": [
{
"pinnedField": "DESCRIPTION_1",
"text": "Connect social accounts and schedule posts with the AIsa API."
},
{
"text": "Build social publishing into your application."
}
],
"finalUrls": [
"https://example.com/landing"
],
"headlines": [
{
"pinnedField": "HEADLINE_1",
"text": "Social Media API"
},
{
"text": "Schedule Your Posts"
},
{
"text": "Build With AIsa"
}
]
},
"schema": {
"additionalProperties": true,
"properties": {
"assetGroup": {
"additionalProperties": false,
"description": "Google Performance Max only. Replaces whole asset roles on the ad's asset group. Returns 422 on any other platform or channel.",
"properties": {
"businessName": {
"description": "Replaces the BUSINESS_NAME asset.",
"maxLength": 25,
"minLength": 1,
"type": "string"
},
"descriptions": {
"description": "Replaces every DESCRIPTION asset. At least one must be 60 characters or fewer.",
"items": {
"maxLength": 90,
"minLength": 1,
"type": "string"
},
"maxItems": 5,
"minItems": 2,
"type": "array",
"uniqueItems": true
},
"finalUrl": {
"description": "Replaces the asset group's final URL.",
"format": "uri",
"pattern": "^https?://",
"type": "string"
},
"headlines": {
"description": "Replaces every HEADLINE asset on the group.",
"items": {
"maxLength": 30,
"minLength": 1,
"type": "string"
},
"maxItems": 15,
"minItems": 3,
"type": "array",
"uniqueItems": true
},
"images": {
"additionalProperties": false,
"description": "Public HTTP(S) image URLs. Each role you send replaces that role's images; roles you omit stay. GIF, JPEG or PNG, at most 5120 KB per image.",
"properties": {
"landscape": {
"description": "Replaces MARKETING_IMAGE assets. Aspect ratio 1.91:1, minimum 600 x 314 pixels.",
"items": {
"format": "uri",
"pattern": "^https?://",
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"logo": {
"description": "Replaces LOGO assets. Aspect ratio 1:1, minimum 128 x 128 pixels.",
"items": {
"format": "uri",
"pattern": "^https?://",
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"square": {
"description": "Replaces SQUARE_MARKETING_IMAGE assets. Aspect ratio 1:1, minimum 300 x 300 pixels.",
"items": {
"format": "uri",
"pattern": "^https?://",
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"longHeadline": {
"description": "Replaces the LONG_HEADLINE asset.",
"maxLength": 90,
"minLength": 1,
"type": "string"
},
"youtubeVideoIds": {
"description": "Replaces YOUTUBE_VIDEO assets with existing YouTube video ids. Video uploads and arbitrary video URLs are not supported.",
"items": {
"pattern": "^[A-Za-z0-9_-]{11}$",
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"budget": {
"properties": {
"amount": {
"description": "Minimum varies by platform: TikTok=$20, Pinterest=$5, others=$1",
"type": "number"
},
"type": {
"description": "OpenAI Ads accepts both and sets the campaign's single spend cap, replacing the previous daily or lifetime cap. A daily cap cannot go back to lifetime (422).",
"enum": [
"daily",
"lifetime"
],
"type": "string"
}
},
"type": "object"
},
"connectionId": {
"description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
},
"creative": {
"description": "Replace or patch the ad's creative. Meta, TikTok, and LinkedIn. Meta: patch-style. Pass any subset: omitted fields are preserved from the live creative, including media (`image_hash`/`video_id` reused, no re-upload) and `url_tags`.",
"properties": {
"body": {
"type": "string"
},
"businessName": {
"description": "Google Display only. Replaces the responsive display ad's business name.",
"maxLength": 25,
"minLength": 1,
"type": "string"
},
"callToAction": {
"type": "string"
},
"catalogFormat": {
"description": "Meta catalog template ads only. Rebuilds the creative with this `template_data.format_option` (same mapping as on create) and repoints the ad at the new creative.",
"enum": [
"single_image",
"carousel_images_multi_items",
"carousel_images_single_item",
"carousel_slideshows"
],
"type": "string"
},
"creativeFeatures": {
"additionalProperties": {
"enum": [
"OPT_IN",
"OPT_OUT"
],
"type": "string"
},
"description": "Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT.",
"type": "object"
},
"description": {
"description": "Link description slot (Meta `link_data.description` / `video_data.link_description`, LinkedIn creative description).",
"maxLength": 255,
"type": "string"
},
"existingCreativeId": {
"description": "Meta only. Repoint the ad at an existing library creative (from GET /apis/v1/ads/creatives); all other creative fields are ignored.",
"type": "string"
},
"headline": {
"description": "Meta and LinkedIn (TikTok has no headline slot)",
"type": "string"
},
"imageUrl": {
"format": "uri",
"type": "string"
},
"linkUrl": {
"format": "uri",
"type": "string"
},
"longHeadline": {
"description": "Google Display only. Replaces the responsive display ad's long headline.",
"maxLength": 90,
"minLength": 1,
"type": "string"
},
"promotion": {
"description": "Not supported. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Any object is rejected with 400 invalid_field_value.",
"type": [
"object",
"null"
]
},
"squareImageUrl": {
"description": "Google Display only. Uploaded as a new square (1:1) marketing image asset that replaces the current one.",
"format": "uri",
"type": "string"
},
"videoId": {
"description": "Meta only. Reuse an already-uploaded ad video (from POST /apis/v1/ads/videos or GET /apis/v1/ads/videos) instead of re-uploading via videoUrl.",
"type": "string"
},
"videoUrl": {
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"demandGen": {
"additionalProperties": false,
"description": "Google Demand Gen only. Returns 422 on any other platform or channel.",
"properties": {
"audience": {
"additionalProperties": false,
"description": "Created as a Google Audience and attached to the ad group. Send at least one dimension. Ids are numeric Google ids (user lists, interest categories, custom audiences) from the same customer.",
"properties": {
"ageRanges": {
"items": {
"properties": {
"max": {
"description": "Omit for no upper bound.",
"enum": [
24,
34,
44,
54,
64
],
"type": "integer"
},
"min": {
"enum": [
18,
25,
35,
45,
55,
65
],
"type": "integer"
}
},
"required": [
"min"
],
"type": "object"
},
"maxItems": 6,
"minItems": 1,
"type": "array"
},
"customAudiences": {
"items": {
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"genders": {
"items": {
"enum": [
"male",
"female",
"undetermined"
],
"type": "string"
},
"maxItems": 3,
"minItems": 1,
"type": "array"
},
"userInterests": {
"items": {
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"userLists": {
"items": {
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"audienceId": {
"description": "Attach an existing Google Audience by numeric id instead of audience. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"type": "string"
},
"businessName": {
"maxLength": 25,
"type": "string"
},
"callToAction": {
"description": "Image and carousel ads only.",
"maxLength": 25,
"type": "string"
},
"channels": {
"description": "Replaces the ad group's channel controls. Only the listed channels serve; Google Maps, which this list cannot select, is turned off. Omit to leave the ad group's channel controls unchanged.",
"items": {
"enum": [
"youtube_in_stream",
"youtube_in_feed",
"youtube_shorts",
"discover",
"gmail",
"display"
],
"type": "string"
},
"minItems": 1,
"type": "array"
},
"descriptions": {
"items": {
"maxLength": 90,
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"finalUrl": {
"format": "uri",
"type": "string"
},
"headlines": {
"items": {
"maxLength": 40,
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"images": {
"additionalProperties": false,
"properties": {
"landscape": {
"items": {
"format": "uri",
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"logo": {
"items": {
"format": "uri",
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"portrait": {
"items": {
"format": "uri",
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"square": {
"items": {
"format": "uri",
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"longHeadlines": {
"description": "Video ads only.",
"items": {
"maxLength": 90,
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"youtubeVideoIds": {
"description": "Video ads only.",
"items": {
"pattern": "^[A-Za-z0-9_-]{11}$",
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"descriptions": {
"description": "Google Search and Display only. Replaces the complete description list. Search takes 2-4, Display 1-5 and rejects pinnedField. No padding or truncation on update.",
"items": {
"properties": {
"pinnedField": {
"description": "Optional fixed description position. Omit to leave the asset unpinned.",
"enum": [
"DESCRIPTION_1",
"DESCRIPTION_2"
],
"type": "string"
},
"text": {
"maxLength": 90,
"minLength": 1,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"finalUrls": {
"description": "Google Search and Display only. Replaces final URLs. Omitted lists stay unchanged. For Performance Max use assetGroup.finalUrl.",
"items": {
"format": "uri",
"type": "string"
},
"minItems": 1,
"type": "array"
},
"headlines": {
"description": "Google Search and Display only. Replaces the complete headline list. Search takes 3-15, Display 1-5 and rejects pinnedField; the count is checked once the ad's channel is known. No padding or truncation on update.",
"items": {
"properties": {
"pinnedField": {
"description": "Optional fixed headline position. Omit to leave the asset unpinned.",
"enum": [
"HEADLINE_1",
"HEADLINE_2",
"HEADLINE_3"
],
"type": "string"
},
"text": {
"maxLength": 30,
"minLength": 1,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"maxItems": 15,
"minItems": 1,
"type": "array"
},
"name": {
"description": "Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.",
"maxLength": 255,
"type": "string"
},
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
},
"targeting": {
"description": "Targeting update. Meta + TikTok: demographics/interests. Google: keyword and device bid adjustment edits only. LinkedIn: locations, B2B facets, audiences. Pinterest / X: return 501.",
"properties": {
"advantage_audience": {
"description": "Meta only. Omit to preserve the existing setting on update. 0 = disabled, 1 = enabled.",
"enum": [
0,
1
],
"type": "integer"
},
"ageMax": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"ageMin": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"countries": {
"description": "ISO 3166-1 alpha-2 codes. On Google this is the FULL new country set for the campaign (same contract as `locations`); on LinkedIn it replaces the campaign's geo criteria.",
"items": {
"type": "string"
},
"type": "array"
},
"devices": {
"description": "Google only. The FULL new set of device bid modifiers for the campaign. Entries are a device name alone (targeted, bid modifier reset to 1) or { device, bidModifier }.",
"items": {
"oneOf": [
{
"enum": [
"MOBILE",
"DESKTOP",
"TABLET",
"CONNECTED_TV"
],
"type": "string"
},
{
"properties": {
"bidModifier": {
"description": "Google device bid modifier. 0 switches the device off (minus 100%); otherwise 0.1 to 10 (minus 90% to plus 900%). Google rejects any value between 0 and 0.1.",
"maximum": 10,
"minimum": 0,
"type": "number"
},
"device": {
"enum": [
"MOBILE",
"DESKTOP",
"TABLET",
"CONNECTED_TV"
],
"type": "string"
}
},
"required": [
"device"
],
"type": "object"
}
]
},
"type": "array"
},
"interests": {
"description": "Interest objects from /apis/v1/ads/interests. Each must include id and name.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"keywords": {
"description": "Google only. The FULL desired set of positive keywords for the entire ad group. Omit to leave positives unchanged; [] removes all positives. Negatives are independent.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"matchType": {
"enum": [
"exact",
"phrase",
"broad"
],
"type": "string"
},
"text": {
"maxLength": 80,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
}
]
},
"type": "array"
},
"languages": {
"description": "Google only. The FULL new language set for the campaign, as Google language codes (ISO 639-1, plus variants such as `zh_CN`). An unknown code returns 400.",
"items": {
"type": "string"
},
"type": "array"
},
"locations": {
"description": "Google and LinkedIn. The FULL new location set for the campaign. Bare country-code array, or an object with countries/regions/cities/zips/metros key lists (`key` from GET /apis/v1/ads/targeting/search?dimension=geo).",
"oneOf": [
{
"items": {
"description": "ISO 3166-1 alpha-2 country code.",
"type": "string"
},
"type": "array"
},
{
"properties": {
"cities": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"countries": {
"items": {
"type": "string"
},
"type": "array"
},
"metros": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"regions": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"zips": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
]
},
"negativeKeywords": {
"description": "Google only. The FULL desired set of negative keywords for the entire ad group, independent of positives. Omit to leave negatives unchanged; [] removes all negatives.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"matchType": {
"enum": [
"exact",
"phrase",
"broad"
],
"type": "string"
},
"text": {
"maxLength": 80,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
}
]
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"required": true
},
"x-aisa-status": "enabled",
"x-aisa-pricing": {
"description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
"kind": "no_customer_charge"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
}
}
Cost and request rules
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.
Available options:
spend Path Parameters
Query Parameters
The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.
Pattern:
^adc_[0-9A-Za-z]+$Body
application/json
Google Performance Max only. Replaces whole asset roles on the ad's asset group. Returns 422 on any other platform or channel.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The ads connection (adc_...), when not sent as the connectionId query parameter.
Pattern:
^adc_[0-9A-Za-z]+$Replace or patch the ad's creative. Meta, TikTok, and LinkedIn. Meta: patch-style. Pass any subset: omitted fields are preserved from the live creative, including media (image_hash/video_id reused, no re-upload) and url_tags.
Show child attributes
Show child attributes
Google Demand Gen only. Returns 422 on any other platform or channel.
Show child attributes
Show child attributes
Google Search and Display only. Replaces the complete description list. Search takes 2-4, Display 1-5 and rejects pinnedField. No padding or truncation on update.
Required array length:
1 - 5 elementsShow child attributes
Show child attributes
Google Search and Display only. Replaces final URLs. Omitted lists stay unchanged. For Performance Max use assetGroup.finalUrl.
Minimum array length:
1Google Search and Display only. Replaces the complete headline list. Search takes 3-15, Display 1-5 and rejects pinnedField; the count is checked once the ad's channel is known. No padding or truncation on update.
Required array length:
1 - 15 elementsShow child attributes
Show child attributes
Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.
Maximum string length:
255Available options:
active, paused Targeting update. Meta + TikTok: demographics/interests. Google: keyword and device bid adjustment edits only. LinkedIn: locations, B2B facets, audiences. Pinterest / X: return 501.
Show child attributes
Show child attributes