> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/developer/integrate/openapi/campaign.md).

# Campaign

Campaigns

## Search Campaigns

> Search all Campaigns this user has access to

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Campaign":{"properties":{"campaignId":{"description":"The Campaign Id","type":"integer"},"ownerId":{"description":"The userId of the User that owns this Campaign","type":"integer"},"type":{"description":"The type of campaign, either list, ad, playlist or media","type":"string"},"campaign":{"description":"The name of the Campaign","type":"string"},"isLayoutSpecific":{"description":"A 0|1 flag to indicate whether this is a Layout specific Campaign or not.","type":"integer"},"numberLayouts":{"description":"The number of Layouts associated with this Campaign","type":"integer"},"totalDuration":{"description":"The total duration of the campaign (sum of layout's durations)","type":"integer"},"tags":{"description":"Tags associated with this Campaign, array of TagLink objects","type":"array","items":{"$ref":"#/components/schemas/TagLink"}},"folderId":{"description":"The id of the Folder this Campaign belongs to","type":"integer"},"permissionsFolderId":{"description":"The id of the Folder responsible for providing permissions for this Campaign","type":"integer"},"cyclePlaybackEnabled":{"description":"Flag indicating whether this Campaign has cycle based playback enabled","type":"integer"},"playCount":{"description":"In cycle based playback, how many plays should each Layout have before moving on?","type":"integer"},"listPlayOrder":{"description":"In list campaign types, how should the layouts play out?","type":"string"},"targetType":{"description":"For an ad campaign, what's the target type, plays|budget|imp","type":"string"},"target":{"description":"For an ad campaign, what's the target (expressed in targetType)","type":"integer"},"startDt":{"description":"For an ad campaign, what's the start date","type":"integer"},"endDt":{"description":"For an ad campaign, what's the end date","type":"integer"},"plays":{"description":"The number of plays achived by this campaign","type":"integer"},"spend":{"description":"The amount of spend in cents/pence/etc","type":"number","format":"double"},"impressions":{"description":"The number of impressions achived by this campaign","type":"number","format":"double"},"lastPopId":{"description":"The latest proof of play ID aggregated into the stats","type":"integer"},"ref1":{"description":"Reference field 1","type":"string"},"ref2":{"description":"Reference field 1","type":"string"},"ref3":{"description":"Reference field 1","type":"string"},"ref4":{"description":"Reference field 1","type":"string"},"ref5":{"description":"Reference field 1","type":"string"}}},"TagLink":{"properties":{"tag":{"description":"The Tag","type":"string"},"tagId":{"description":"The Tag ID","type":"integer"},"value":{"description":"The Tag Value","type":"string"}}}}},"paths":{"/campaign":{"get":{"tags":["campaign"],"summary":"Search Campaigns","description":"Search all Campaigns this user has access to","operationId":"campaignSearch","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"query","description":"Filter by Campaign Id","required":false},{"schema":{"type":"string"},"name":"name","in":"query","description":"Filter by Name","required":false},{"schema":{"type":"string"},"name":"tags","in":"query","description":"Filter by Tags","required":false},{"schema":{"type":"integer"},"name":"exactTags","in":"query","description":"A flag indicating whether to treat the tags filter as an exact match","required":false},{"schema":{"type":"string"},"name":"logicalOperator","in":"query","description":"When filtering by multiple Tags, which logical operator should be used? AND|OR","required":false},{"schema":{"type":"integer"},"name":"hasLayouts","in":"query","description":"Filter by has layouts","required":false},{"schema":{"type":"integer"},"name":"isLayoutSpecific","in":"query","description":"Filter by whether this Campaign is specific to a Layout or User added","required":false},{"schema":{"type":"integer"},"name":"retired","in":"query","description":"Filter by retired","required":false},{"schema":{"type":"integer"},"name":"totalDuration","in":"query","description":"Should we total the duration?","required":false},{"schema":{"type":"string"},"name":"embed","in":"query","description":"Embed related data such as layouts, permissions, tags and events","required":false},{"schema":{"type":"integer"},"name":"folderId","in":"query","description":"Filter by Folder ID","required":false}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}}}}}}}
```

## Add Campaign

> Add a Campaign

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Campaign":{"properties":{"campaignId":{"description":"The Campaign Id","type":"integer"},"ownerId":{"description":"The userId of the User that owns this Campaign","type":"integer"},"type":{"description":"The type of campaign, either list, ad, playlist or media","type":"string"},"campaign":{"description":"The name of the Campaign","type":"string"},"isLayoutSpecific":{"description":"A 0|1 flag to indicate whether this is a Layout specific Campaign or not.","type":"integer"},"numberLayouts":{"description":"The number of Layouts associated with this Campaign","type":"integer"},"totalDuration":{"description":"The total duration of the campaign (sum of layout's durations)","type":"integer"},"tags":{"description":"Tags associated with this Campaign, array of TagLink objects","type":"array","items":{"$ref":"#/components/schemas/TagLink"}},"folderId":{"description":"The id of the Folder this Campaign belongs to","type":"integer"},"permissionsFolderId":{"description":"The id of the Folder responsible for providing permissions for this Campaign","type":"integer"},"cyclePlaybackEnabled":{"description":"Flag indicating whether this Campaign has cycle based playback enabled","type":"integer"},"playCount":{"description":"In cycle based playback, how many plays should each Layout have before moving on?","type":"integer"},"listPlayOrder":{"description":"In list campaign types, how should the layouts play out?","type":"string"},"targetType":{"description":"For an ad campaign, what's the target type, plays|budget|imp","type":"string"},"target":{"description":"For an ad campaign, what's the target (expressed in targetType)","type":"integer"},"startDt":{"description":"For an ad campaign, what's the start date","type":"integer"},"endDt":{"description":"For an ad campaign, what's the end date","type":"integer"},"plays":{"description":"The number of plays achived by this campaign","type":"integer"},"spend":{"description":"The amount of spend in cents/pence/etc","type":"number","format":"double"},"impressions":{"description":"The number of impressions achived by this campaign","type":"number","format":"double"},"lastPopId":{"description":"The latest proof of play ID aggregated into the stats","type":"integer"},"ref1":{"description":"Reference field 1","type":"string"},"ref2":{"description":"Reference field 1","type":"string"},"ref3":{"description":"Reference field 1","type":"string"},"ref4":{"description":"Reference field 1","type":"string"},"ref5":{"description":"Reference field 1","type":"string"}}},"TagLink":{"properties":{"tag":{"description":"The Tag","type":"string"},"tagId":{"description":"The Tag ID","type":"integer"},"value":{"description":"The Tag Value","type":"string"}}}}},"paths":{"/campaign":{"post":{"tags":["campaign"],"summary":"Add Campaign","description":"Add a Campaign","operationId":"campaignAdd","responses":{"201":{"description":"successful operation","headers":{"Location":{"description":"Location of the new record","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Type of campaign, either list|ad"},"name":{"type":"string","description":"Name for this Campaign"},"folderId":{"type":"integer","description":"Folder ID to which this object should be assigned to"},"layoutIds":{"type":"array","description":"An array of layoutIds to assign to this Campaign, in order."},"cyclePlaybackEnabled":{"type":"integer","description":"When cycle based playback is enabled only 1 Layout from this Campaign will be played each time\r\n     * it is in a Schedule loop. The same Layout will be shown until the 'Play count' is achieved."},"playCount":{"type":"integer","description":"In cycle based playback, how many plays should each Layout have before moving on?"},"listPlayOrder":{"type":"string","description":"In layout list, how should campaigns in the schedule with the same play order be played?"},"targetType":{"type":"string","description":"For ad campaigns, how do we measure the target? plays|budget|imp"},"target":{"type":"integer","description":"For ad campaigns, what is the target count for playback over the entire campaign"}},"required":["type","name"]}}}}}}}}
```

## Edit Campaign

> Edit an existing Campaign

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Campaign":{"properties":{"campaignId":{"description":"The Campaign Id","type":"integer"},"ownerId":{"description":"The userId of the User that owns this Campaign","type":"integer"},"type":{"description":"The type of campaign, either list, ad, playlist or media","type":"string"},"campaign":{"description":"The name of the Campaign","type":"string"},"isLayoutSpecific":{"description":"A 0|1 flag to indicate whether this is a Layout specific Campaign or not.","type":"integer"},"numberLayouts":{"description":"The number of Layouts associated with this Campaign","type":"integer"},"totalDuration":{"description":"The total duration of the campaign (sum of layout's durations)","type":"integer"},"tags":{"description":"Tags associated with this Campaign, array of TagLink objects","type":"array","items":{"$ref":"#/components/schemas/TagLink"}},"folderId":{"description":"The id of the Folder this Campaign belongs to","type":"integer"},"permissionsFolderId":{"description":"The id of the Folder responsible for providing permissions for this Campaign","type":"integer"},"cyclePlaybackEnabled":{"description":"Flag indicating whether this Campaign has cycle based playback enabled","type":"integer"},"playCount":{"description":"In cycle based playback, how many plays should each Layout have before moving on?","type":"integer"},"listPlayOrder":{"description":"In list campaign types, how should the layouts play out?","type":"string"},"targetType":{"description":"For an ad campaign, what's the target type, plays|budget|imp","type":"string"},"target":{"description":"For an ad campaign, what's the target (expressed in targetType)","type":"integer"},"startDt":{"description":"For an ad campaign, what's the start date","type":"integer"},"endDt":{"description":"For an ad campaign, what's the end date","type":"integer"},"plays":{"description":"The number of plays achived by this campaign","type":"integer"},"spend":{"description":"The amount of spend in cents/pence/etc","type":"number","format":"double"},"impressions":{"description":"The number of impressions achived by this campaign","type":"number","format":"double"},"lastPopId":{"description":"The latest proof of play ID aggregated into the stats","type":"integer"},"ref1":{"description":"Reference field 1","type":"string"},"ref2":{"description":"Reference field 1","type":"string"},"ref3":{"description":"Reference field 1","type":"string"},"ref4":{"description":"Reference field 1","type":"string"},"ref5":{"description":"Reference field 1","type":"string"}}},"TagLink":{"properties":{"tag":{"description":"The Tag","type":"string"},"tagId":{"description":"The Tag ID","type":"integer"},"value":{"description":"The Tag Value","type":"string"}}}}},"paths":{"/campaign/{campaignId}":{"put":{"tags":["campaign"],"summary":"Edit Campaign","description":"Edit an existing Campaign","operationId":"campaignEdit","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"path","description":"The Campaign ID to Edit","required":true}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for this Campaign"},"folderId":{"type":"integer","description":"Folder ID to which this object should be assigned to"},"manageLayouts":{"type":"integer","description":"Flag indicating whether to manage layouts or not. Default to no."},"layoutIds":{"type":"array","description":"An array of layoutIds to assign to this Campaign, in order."},"cyclePlaybackEnabled":{"type":"integer","description":"When cycle based playback is enabled only 1 Layout from this Campaign will be played each time it is in a Schedule loop. The same Layout will be shown until the 'Play count' is achieved."},"playCount":{"type":"integer","description":"In cycle based playback, how many plays should each Layout have before moving on?"},"listPlayOrder":{"type":"string","description":"In layout list, how should campaigns in the schedule with the same play order be played?"},"targetType":{"type":"string","description":"For ad campaigns, how do we measure the target? plays|budget|imp"},"target":{"type":"integer","description":"For ad campaigns, what is the target count for playback over the entire campaign"},"startDt":{"type":"string","description":"For ad campaigns, what is the start date","format":"date-time"},"endDt":{"type":"string","description":"For ad campaigns, what is the start date","format":"date-time"},"displayGroupIds[]":{"type":"array","description":"For ad campaigns, which display groups should the campaign be run on?"},"ref1":{"type":"string","description":"An optional reference field"},"ref2":{"type":"string","description":"An optional reference field"},"ref3":{"type":"string","description":"An optional reference field"},"ref4":{"type":"string","description":"An optional reference field"},"ref5":{"type":"string","description":"An optional reference field"}},"required":["name"]}}}}}}}}
```

## Delete Campaign

> Delete an existing Campaign

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/campaign/{campaignId}":{"delete":{"tags":["campaign"],"summary":"Delete Campaign","description":"Delete an existing Campaign","operationId":"campaignDelete","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"path","description":"The Campaign ID to Delete","required":true}],"responses":{"204":{"description":"successful operation"}}}}}}
```

## Assign Layout

> Assign a Layout to a Campaign. Please note that as of v3.0.0 this API no longer accepts multiple layoutIds.

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/campaign/layout/assign/{campaignId}":{"post":{"tags":["campaign"],"summary":"Assign Layout","description":"Assign a Layout to a Campaign. Please note that as of v3.0.0 this API no longer accepts multiple layoutIds.","operationId":"campaignAssignLayout","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"path","description":"The Campaign ID","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"layoutId":{"type":"integer","description":"Layout ID to Assign: Please note that as of v3.0.0 this API no longer accepts multiple layoutIds."},"daysOfWeek[]":{"type":"array","description":"Ad campaigns: restrict this to certain days of the week (iso week)"},"dayPartId":{"type":"integer","description":"Ad campaigns: restrict this to a day part"},"geoFence":{"type":"string","description":"Ad campaigns: restrict this to a geofence"}},"required":["layoutId"]}}}}}}}}
```

## Remove Layout

> Remove a Layout from a Campaign.

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/campaign/layout/remove/{campaignId}":{"delete":{"tags":["campaign"],"summary":"Remove Layout","description":"Remove a Layout from a Campaign.","operationId":"campaignAssignLayout","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"path","description":"The Campaign ID","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"layoutId":{"type":"integer","description":"Layout ID to remove"},"displayOrder":{"type":"integer","description":"The display order. Omit to remove all occurences of the layout"}},"required":["layoutId"]}}}}}}}}
```

## Campaign Select folder

> Select Folder for Campaign, can also be used with Layout specific Campaign ID

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"campaign","description":"Campaigns"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Campaign":{"properties":{"campaignId":{"description":"The Campaign Id","type":"integer"},"ownerId":{"description":"The userId of the User that owns this Campaign","type":"integer"},"type":{"description":"The type of campaign, either list, ad, playlist or media","type":"string"},"campaign":{"description":"The name of the Campaign","type":"string"},"isLayoutSpecific":{"description":"A 0|1 flag to indicate whether this is a Layout specific Campaign or not.","type":"integer"},"numberLayouts":{"description":"The number of Layouts associated with this Campaign","type":"integer"},"totalDuration":{"description":"The total duration of the campaign (sum of layout's durations)","type":"integer"},"tags":{"description":"Tags associated with this Campaign, array of TagLink objects","type":"array","items":{"$ref":"#/components/schemas/TagLink"}},"folderId":{"description":"The id of the Folder this Campaign belongs to","type":"integer"},"permissionsFolderId":{"description":"The id of the Folder responsible for providing permissions for this Campaign","type":"integer"},"cyclePlaybackEnabled":{"description":"Flag indicating whether this Campaign has cycle based playback enabled","type":"integer"},"playCount":{"description":"In cycle based playback, how many plays should each Layout have before moving on?","type":"integer"},"listPlayOrder":{"description":"In list campaign types, how should the layouts play out?","type":"string"},"targetType":{"description":"For an ad campaign, what's the target type, plays|budget|imp","type":"string"},"target":{"description":"For an ad campaign, what's the target (expressed in targetType)","type":"integer"},"startDt":{"description":"For an ad campaign, what's the start date","type":"integer"},"endDt":{"description":"For an ad campaign, what's the end date","type":"integer"},"plays":{"description":"The number of plays achived by this campaign","type":"integer"},"spend":{"description":"The amount of spend in cents/pence/etc","type":"number","format":"double"},"impressions":{"description":"The number of impressions achived by this campaign","type":"number","format":"double"},"lastPopId":{"description":"The latest proof of play ID aggregated into the stats","type":"integer"},"ref1":{"description":"Reference field 1","type":"string"},"ref2":{"description":"Reference field 1","type":"string"},"ref3":{"description":"Reference field 1","type":"string"},"ref4":{"description":"Reference field 1","type":"string"},"ref5":{"description":"Reference field 1","type":"string"}}},"TagLink":{"properties":{"tag":{"description":"The Tag","type":"string"},"tagId":{"description":"The Tag ID","type":"integer"},"value":{"description":"The Tag Value","type":"string"}}}}},"paths":{"/campaign/{id}/selectfolder":{"put":{"tags":["campaign"],"summary":"Campaign Select folder","description":"Select Folder for Campaign, can also be used with Layout specific Campaign ID","operationId":"campaignSelectFolder","parameters":[{"schema":{"type":"integer"},"name":"campaignId","in":"path","description":"The Campaign ID or Layout specific Campaign ID","required":true}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"folderId":{"type":"integer","description":"Folder ID to which this object should be assigned to"}},"required":[]}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xibosignage.com/developer/integrate/openapi/campaign.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.