library_placement_update
Change the name, the description, or the rules of a Placement of your organization.
Ask to change a slot of your own. The agent changes the name, the description, or the rules. A field that the call leaves out stays as it is. The new rules replace the stored list, so the agent sends the whole list.
“Make the partner feed placement need 1080 pixels of width.”
When a Variation names the Placement, the next read of that Variation shows its new broken rules. A global Placement is read-only, and a change of it answers not_found.
This tool is part of the job Bring your own creative.
Reference
Change the name, the description or the rules of a Placement of your organization. A field that the call leaves out stays as it is. The new rules replace the stored list: send the whole list. The rules can change while a Variation names the Placement: the next read of the Variation shows the new brokenRules. A Placement is the slot where a provider shows an ad, for example Meta Stories video. It holds rules that an Asset should hold to fit the slot. The rules are advice: they never block a write. type and channel never change after the create. A global row (isGlobal is true) is held by AdCrunch for each organization. You read it and use it. A change of a global row, and a delete of it, answer not_found.
Input
| Argument | Type | Required | Description |
|---|---|---|---|
description |
string or null | no | A free text. A blank text or null stores no description. On an update, leave it out to keep the description. |
name |
string | no | The name, 1 to 80 characters. AdCrunch trims it. It must be unique, ignoring case, among the ones that your organization sees: for a Placement, among the Placements of the same channel. |
placement_id |
string | yes | The id of a Placement (plm_…). library_placement_list gives it. A Placement of AdCrunch (isGlobal) and a Placement of your organization both work. |
rules |
array of object | no | The rules that an Asset should hold, 20 at most. All of them must hold, and there is no “or” between two rules. A rule is { type, operator: { condition, value } }. type is one of width, height, ratio, size, mime and duration. duration is for a video Placement only. Units: width and height are pixels. size is bytes. duration is milliseconds. A ratio value is a pair [width, height] of whole numbers, for example [9, 16]. Two ratios are equal when they differ by 1 % at most. A mime value is a string such as image/jpeg. condition is one of eq, ne, lt, lte, gt, gte and in. mime takes eq, ne and in only. in takes a list of values: [[4, 5], [1, 1]] means “the ratio is 4:5 or 1:1”. Example of three rules: [{"type":"ratio","operator":{"condition":"in","value":[[4,5],[1,1]]}},{"type":"width","operator":{"condition":"gte","value":600}},{"type":"mime","operator":{"condition":"in","value":["image/jpeg","image/png"]}}]. |
rules[].type |
width or height or size or ratio or mime or duration |
yes | |
rules[].operator |
object | yes | Only when type is width. |
rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
rules[].operator |
object | yes | Only when type is height. |
rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
rules[].operator |
object | yes | Only when type is size. |
rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
rules[].operator |
object | yes | Only when type is ratio. |
rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is eq. |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is ne. |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is lt. |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is lte. |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is gt. |
rules[].operator.value |
array of any, 2 items | yes | Only when condition is gte. |
rules[].operator.value |
array of (array of any, 2 items), 1 to 50 items | yes | Only when condition is in. |
rules[].operator |
object | yes | Only when type is mime. |
rules[].operator.condition |
eq or ne or in |
yes | |
rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is eq. |
rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is ne. |
rules[].operator.value |
array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when condition is in. |
rules[].operator |
object | yes | Only when type is duration. |
rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
Output
A successful call returns this object in structuredContent.
| Field | Type | Always present | Description |
|---|---|---|---|
placement |
object | yes | The Placement with its new name, description or rules. |
placement.channel |
one of meta, tiktok, snapchat, google_search, google_pmax, google_display, youtube, programmatic_display, linkedin, x |
yes | The channel of a Line Item that the Placement belongs to. It never changes. |
placement.createdAt |
number | yes | Milliseconds since the Unix epoch, UTC. |
placement.createdBy |
string or null | yes | The user who created the Placement. null on a global row. |
placement.deletedAt |
number or null | yes | Always null here. A deleted Placement is not answered. |
placement.description |
string or null | yes | A free text. null when the Placement has none. |
placement.id |
string | yes | The id of the Placement, plm_…. |
placement.isGlobal |
boolean | yes | true on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it. |
placement.name |
string | yes | The name, 1 to 80 characters. It is unique, ignoring case, among the Placements of the channel that the organization sees. |
placement.organizationId |
string or null | yes | The organization that owns the Placement. null on a global row. |
placement.params |
object | yes | |
placement.params.type |
image or video |
yes | |
placement.params.rules |
array of object, at most 20 items | yes | Only when type is image. |
placement.params.rules[].type |
width or height or size or ratio or mime |
yes | |
placement.params.rules[].operator |
object | yes | Only when type is width. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is height. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is size. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is ratio. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (array of any, 2 items), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is mime. |
placement.params.rules[].operator.condition |
eq or ne or in |
yes | |
placement.params.rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules |
array of object, at most 20 items | yes | Only when type is video. |
placement.params.rules[].type |
width or height or size or ratio or mime or duration |
yes | |
placement.params.rules[].operator |
object | yes | Only when type is width. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is height. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is size. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is ratio. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
array of any, 2 items | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (array of any, 2 items), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is mime. |
placement.params.rules[].operator.condition |
eq or ne or in |
yes | |
placement.params.rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
string, 1 to 255 characters | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when condition is in. |
placement.params.rules[].operator |
object | yes | Only when type is duration. |
placement.params.rules[].operator.condition |
eq or ne or lt or lte or gt or gte or in |
yes | |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is eq. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is ne. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is lte. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gt. |
placement.params.rules[].operator.value |
integer, at least 0 | yes | Only when condition is gte. |
placement.params.rules[].operator.value |
array of (integer, at least 0), 1 to 50 items | yes | Only when condition is in. |
placement.type |
one of image, video |
yes | The kind of Asset that the slot takes. It never changes, and it equals params.type. |
placement.updatedAt |
number or null | yes | When the Placement last changed. null until its first update. |
Failure codes
A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.
not_foundinvalid_nameinvalid_rulesname_takenorganization_unentitledforbiddeninvalid_requestinternal_error
Scope
The token must hold library:write. Auth & scopes lists each scope.
Annotations
A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.
- Writes. The tool can change data.
- Not destructive. The tool makes only additive changes.
- Idempotent. A second call with the same arguments changes nothing more.
- Closed world. The tool reads and writes the data of AdCrunch only.
Example
The arguments:
{
"name": "Reels short cut",
"placement_id": "plm_4b8d27",
"rules": [
{
"operator": {
"condition": "eq",
"value": [
9,
16
]
},
"type": "ratio"
},
{
"operator": {
"condition": "lte",
"value": 30000
},
"type": "duration"
}
]
}
The result, in structuredContent:
{
"placement": {
"channel": "meta",
"createdAt": 1790000500000,
"createdBy": "usr_2e5b84",
"deletedAt": null,
"description": "Our own cut for Reels, never over 30 seconds.",
"id": "plm_4b8d27",
"isGlobal": false,
"name": "Reels short cut",
"organizationId": "org_3a7f10",
"params": {
"rules": [
{
"operator": {
"condition": "eq",
"value": [
9,
16
]
},
"type": "ratio"
},
{
"operator": {
"condition": "lte",
"value": 30000
},
"type": "duration"
}
],
"type": "video"
},
"type": "video",
"updatedAt": 1790000900000
}
}