Create Layouts via API confusing issues

So I am trying to create a Layout from the API but I am running into some troubles or confusion.

So if I understand correctly a Layout has many regions, which have a playlist. But I find the relations between them confusing, especially the thing about that there is a parent layout.

So this was my path:

Create Layout looks good

POST {{url}}/api/layout

btw: I only take show the relevant reponse parts

{
    "layoutId": 54,
    "regions": [
        {
            "regionId": 81,
            "layoutId": 54,
            "regionPlaylist": {
                "playlistId": 81,

Cannot add anything direclty to playlist 81:

POST {{url}}/api/playlist/widget/webpage/81 returns 422, This Layout is not a Draft, please checkout

Or check it out ({{url}}/api/layout/checkout/54) returns 422, Layout is already checked out

So I learn about childLayout from a forum Post, so I look for the child layout:

Child Layout

GET {{url}}/api/layout?parentId=54

[
    {
        "layoutId": 57,
        "parentId": 54,
        "regions": [],
        "tags": null,
    }
]

So Ok, I don’t really understand, why it works like this, but I guess you need to have something editable, while keeping the original version.

So here I don’t see existing regions. so:

Add region to child layout

POST {{url}}/api/region/57

{
    "regionId": 87,
    "layoutId": 57,
    "regionPlaylist": {
        "playlistId": 87,
        "widgets": [],

So that looks good to, I add a widget:

Add Widget

POST {{url}}/api/playlist/widget/webpage/87

{
    "widgetId": 48,
    "playlistId": "87",

PUT {{url}}/api/playlist/widget/48?webpage

{
    "widgetId": 48,
    "playlistId": 87,

So again looks good.

Region does not exists on child layout

GET {{url}}/api/layout?layoutId=57

[
    {
        "layoutId": 57,
        "regions": [],

Regions is somehow empty, so I don’t know where that went.

Can’t see it in UI

In the UI there is only the ParentLayout diplayed id = 54

I can try to publish layout

PUT {{url}}/api/layout/publish/57

{
“layoutId”: 57,
“parentId”: 54,
“publishedStatusId”: 2,
“publishedStatus”: “Draft”,
“publishedDate”: null,
“status”: 3,
“regions”: [],
}

But that does not do anything.

Remedy: Delete the empty region

So I go to the ui, where I have the parentLayout id 54, as I go in, the layout has TWO regions:

  • An empty region (created by default)
  • The region with the widget I created.

I then delete the empty region. Then I can publish from the UI, and it bumps the ID to 57

So what am I doing wrong:

  • I can not access the region that is created by default, deleting or adding widgets via API was never possible via API, as it said the layout is in not in draft stage.
  • Or is this just a bug?

Note that the region was created with a post to id 57, but was never available under that layout. In the editor both region were showing.

btw: I am running on hosted, https://roli.xigo.com.uk Version 2.3.3, also

So I got curious to see, what the UI does, and then I started to think the above behaviour might actually be a bug. So I dove into the codebase and found my answer.

My main issues, was that the layout get action does not actually return the regions, unless you ask for it with a queryParamter embed

So {{url}}/api/layout?layoutId=6&embed=regions seems to do the trick. I guess this should solve my problem.

It is actually documented in the API docs, however I only managed to find it after the fact. As text searching region was not so usefull, as the relevant information was collapsed.