> 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/getting-started-with-postman.md).

# Getting Started with Postman

## Introduction

This guide is applicable for CMS 1.8 and later versions and assumes that you already have a working CMS. Players need to be version 1.8.0-rc1 or later and [XMR](http://xibo.org.uk/manual-tempel/en/xmr.html) also needs to be configured.

As a first step, you will need to decide what application you will want to use to connect to the API.

In this guide we will use [Postman](https://www.getpostman.com/) as an example application.

The API documentation can be found in the [Developer manual](https://xibo.org.uk/docs/developer/) under the [Integration](https://xibo.org.uk/docs/developer/integrating-with-xibo) section.

## CMS Application

No matter what application you want to use, you will have to create a new application in your CMS Instance.

* Navigate to Applications under the Administration section of the main CMS menu and click the **Add Application** button:

![](/files/48358cfaf130742649b9b63a6143d05d7db04360)

* Give your Application a Name and click **Save**:

[![](/files/7ccd2537f85eef24f747a40de316e46a17a6dbd3)](https://account.xibosignage.com/img/developer/a054e5754f73650dfe90aeefaa76d4269f25b14f.png)

After saving, the Edit Application form will open.

The **Client Id** and **Client Secret** will be needed later. For this example, check the **Client Credentials?** and **Is Confidential?** checkboxes for the application:

[![](/files/ae3b2b5f3b36a35a347379869018b25d88ae5f88)](https://account.xibosignage.com/img/developer/f4f8fc5f929b425ea5047d3479a2514b8d818628_2_428x500.png)

* From the **Sharing** tab, check **Full Account Access**.
* Click **Save**.

[![](/files/9173c08ab04ad93e0780f99622b841e6e9d3802c)](https://account.xibosignage.com/img/developer/9067bed4f8073db3df0dcdb08a90105540cc1e25_2_356x500.png)

## Application Configuration

Once the application is created in the CMS and you have the **Client Id** and **Client Secret**, configure the application to communicate with CMS.

Postman will be used for this example.

Environment

Select the gear icon at the top right of the Postman application and select **Manage Environments**:

![](/files/3636d66545022953f963b0354d6ee3cb668333e0)

Click the Add button and configure your environment:

![](/files/b3986749b96df309f07315662317932f90c0a20f)

* *access\_token* — you will get this with your first API call.
* *url* — your CMS address
* *clientId* and *clientSecret* — keys from creating the application in the CMS.
* *hardwareKey / serverKey / version* — are not required (but can be used in some calls).

Once configured, make sure Postman is set to use your environment — in this example “Local 1.8” is the environment name.

### Add Xibo APIs to Postman

Postman can import Xibo’s swagger.json file which will add a collection containing all of our documented APIs. On the top left side there is the ‘Import’ button; select it, choose “Link”, and paste in the link to our swagger.json file.

[![](/files/e7122dc70a77928e5f9eee4edf178364fb9ae4e9)](https://account.xibosignage.com/img/developer/231b77c3114ad69c65c0048f0b5455349d59684a_2_690x405.png)

You can find our latest swagger.json file here: <https://xibosignage.com/manual/swagger.json>, however we recommend using the one from the CMS you are connecting to which is available at \<your\_cms\_url>/swagger.json.

#### Configure authorisation

All APIs require authorisation, which can be configured for the entire collection in Postman on the “Authorization” tab.

For this example, the variables created in the environment will be used to fill in the URL / clientId / clientSecret from the “Configure New Token” options. The grant type should be “Client Credentials”.

[![](/files/ef1a50365ec26bb446c046112fe00f9f07ee8f67)](https://account.xibosignage.com/img/developer/0cb838b8dc040e9dc972ca55136fe284f9e91f3c_2_307x500.png)

Once configured, select the **Get New Access Token** button to get and use a new token.

#### Variables

The new collection has a `baseUrl` variable in the Variables tab, which we can set to `{{url}}/api`.

Once we have an access token and have configured everything, we are ready to make our first request. Scroll to the “About” item in the collection, open it and click Send.

## Example — creating a Layout, uploading Media and assigning it

Most calls will require Authorization `Bearer {{access_token}}` in the headers:

![](/files/b4bd2768abf4ef1695c683db9e263812e964861a)

All parameters in `{{}}` like `{{url}}` or `{{clientSecret}}` are set in your environment, so you don’t have to copy the whole access\_token into each API call — instead use `{{access_token}}` in the call’s header.

{% stepper %}
{% step %}

### Create a Layout

Call the Layout create endpoint — you will need to pass the name as a parameter. Additional parameters are available; see the linked API documentation for details.

Reference: [Layout create](http://xibo.org.uk/manual-tempel/api/#!/layout/layoutAdd)

When you create a new layout via the API, the response includes region information (a new Layout comes with an empty full-screen region). Note the returned playlistId for the region — it will be used to assign media to that region.

![](/files/d55d9acd8d79f85dc282c7aea2c311139ac0136c)

After creation, you will see region details in the response:

![](/files/0d0cd0784de2938075064cdd7e3eb2f8b04024fa)
{% endstep %}

{% step %}

### Upload Media to the CMS Library

Use the library upload call in the test collection to upload a new file.

[![](/files/6ae3cea9a2aa30fe0dba6a82e103f4eeaebb08ea)](https://account.xibosignage.com/img/developer/8041528a651660196d7f93df3413c3492b25cb79.png)

On opening, it will be set to upload a new file:

* Click the files button
* Select the media file
* Change the name (optional)
* Click Send

The response will contain the mediaId of the newly uploaded file — keep this for the next step.

There are additional (inactive) parameters available for replace/update behavior:

* oldMediaId — replace an existing mediaId with this upload
* updateInLayouts — flag (1,0) to update this media in all layouts (used with Replace)
* deleteOldRevisions — flag (1,0) to remove or keep old file revisions (used with Replace)
  {% endstep %}

{% step %}

### Assign Media to the Layout (Playlist)

Use the playlist library assign call. You will need the playlistId from the layout region and the mediaId from the upload.

Reference: [Playlist library assign](http://xibo.org.uk/manual-tempel/api/#!/playlist/playlistLibraryAssign)

* playlistId — each region has a playlistId. If you know it (e.g., 3), use that. If not, call GET Layouts (included in the collection) to find it.
* media — an array of mediaId values to assign to the region (at least one required). If you don’t know a mediaId, call GET Media.
* duration — optional parameter to set duration for the assigned media.

![](/files/e85f43676c17e1a3805d21f8778099b17c4047d4)

At this point you have created a Layout, uploaded a Media file, and assigned it to the Layout.
{% endstep %}
{% endstepper %}

Another useful call in the collection:

Action: [Change layout](http://xibo.org.uk/manual-tempel/api/#!/displayGroup/displayGroupActionChangeLayout)

* You’ll need displayGroupId and layoutId.
* Call GET Displays to get displayGroupId — each display has its own displayGroupId.
* Or call GET DisplayGroups to get a display group’s displayGroupId if you have Display Groups set up.
* Call GET Layout to get the layoutId you need.

If you send the change layout action without a specified duration, the layout will be shown according to the layout's duration settings.

## Notes

There are a lot more API calls available; using this guide and the API documentation you should be able to create them yourself.

In all GET calls you can pass additional parameters to filter results — check the API documentation: Swagger UI at <http://xibo.org.uk/manual-tempel/api/#/>

If you find that some calls are not working, please create a new topic in the [Dev Category](https://community.xibo.org.uk/c/dev/dev-questions) on the Xibo Community site.


---

# 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/getting-started-with-postman.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.