# Layout format

> The sunny-layout JSON document — one room's shell and furniture — and how to export and import it over the REST API, MCP, or an embed.

`sunny-layout` is a versioned JSON document describing one room: its shell (size, shape, doors and windows, finishes) and the furniture placed in it. Use it to move a layout between Sunny and a scan-to-plan tool, a CAD pipeline, or your own system.

In the API a room is a **space**, and it’s addressed by its space id (`spc_…`). “Room” and “space” mean the same thing on this page.

## Example

sunny-layout v1

```json
{
  "format": "sunny-layout",
  "version": 1,
  "room": {
    "w": 6,
    "d": 4,
    "openings": [
      {
        "id": "op_V1StGXR8_Z5jdHi6B-myT",
        "kind": "window",
        "side": "back",
        "center": 0.5,
        "width": 1.2,
        "sill": 0.72,
        "height": 0.76
      },
      {
        "id": "op_3ZtqT7bWq0cY8mNn1kLpA",
        "kind": "door",
        "side": "front",
        "center": 0.15,
        "width": 0.9,
        "sill": 0,
        "height": 2.1,
        "hinge": "start"
      }
    ],
    "floorType": "oak",
    "wallColor": "#c7d0c3"
  },
  "placements": [
    {
      "id": 1,
      "catalogId": "conf-table",
      "x": 1.5,
      "y": 1.4,
      "item": { "name": "Conference Table", "w": 3, "d": 1.2 }
    },
    {
      "id": 2,
      "catalogId": "dining-chair",
      "x": 2.75,
      "y": 2.7,
      "item": { "name": "Chair", "w": 0.5, "d": 0.55 },
      "config": { "rotation": 180 }
    }
  ],
  "meta": {
    "name": "Boardroom",
    "exportedAt": "2026-10-05T21:00:00.000Z",
    "generator": "sunny-api"
  }
}
```

## Coordinates and units

* Every length is in **meters**.
* The origin is the room’s top-left interior corner: x runs right, y runs down.
* `room.w` and `room.d` are the interior width and depth.
* A placement’s `x`/`y` is the top-left corner of its footprint.

## Document

| Field        | Type             | Description                                                            |
| ------------ | ---------------- | ---------------------------------------------------------------------- |
| `format`     | `"sunny-layout"` | Required.                                                              |
| `version`    | `number`         | Required. `1` is the only version today.                               |
| `room`       | object           | Required. The shell — see [Room](#room).                               |
| `placements` | array            | Required. The furniture — see [Placements](#placements). May be empty. |
| `meta`       | object           | Optional: `name`, `rationale`, `exportedAt` (ISO 8601), `generator`.   |

`meta.generator` names what wrote the document — `sunny-api` from the REST API, `sunny-mcp` from the MCP server. It’s informational; don’t branch on it. On import, `meta.name` becomes the new version’s name.

## Room

| Field           | Type                                                                                                                           | Description                                                                                                                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `architecture`  | `object`                                                                                                                       | Imported building geometry bound to this room. Round-trips a model already uploaded to Sunny; not something to author by hand.                                                                                                                                                     |
| `h`             | `number`                                                                                                                       | Ceiling height, meters.                                                                                                                                                                                                                                                            |
| `floorMaterial` | `object`                                                                                                                       | Custom floor texture. Round-trips textures already uploaded to Sunny; not something to author by hand.                                                                                                                                                                             |
| `w`required     | `number`                                                                                                                       | Interior width, meters                                                                                                                                                                                                                                                             |
| `d`required     | `number`                                                                                                                       | Interior depth, meters                                                                                                                                                                                                                                                             |
| `openings`      | `object[]`                                                                                                                     | Parametric openings only. Absent/empty = a plain box.                                                                                                                                                                                                                              |
| `footprint`     | `object`                                                                                                                       | Non-rectangular room shape. Absent = the plain w×d rectangle.                                                                                                                                                                                                                      |
| `floorType`     | `"tile" \| "concrete" \| "oak" \| "birch" \| "walnut" \| "espresso" \| "plush" \| "oatmeal" \| "sage" \| "clay" \| "charcoal"` | Present only when the finish isn't the studio's tile default                                                                                                                                                                                                                       |
| `floorColor`    | `string`                                                                                                                       | #rrggbb tint overriding the finish's own color                                                                                                                                                                                                                                     |
| `wallColor`     | `string`                                                                                                                       | Present only when the paint isn't the studio's default plaster                                                                                                                                                                                                                     |
| `wallColors`    | `object`                                                                                                                       | Per-wall paint (#rrggbb) over wallColor: a feature wall. Keys are a side (back = y 0, front = y depth, left = x 0, right = x width) or, on a shaped room, a traced outline edge index (as an opening's \`edge\`), which wins over its side. Paints the wall's room-side face only. |

Fields the room doesn’t need are left out on export: `floorType` is omitted for the default tile, `wallColor` for the default plaster, `footprint` for a plain rectangle, `openings` for a plain box.

`wallColors` paints single walls, for a feature wall: `{ "left": "#3f5664" }`. A key is a side (`back`, `front`, `left` or `right`) or, on a shaped room, a wall run’s edge index, the same `edge` openings use. Walls it doesn’t name show `wallColor`. It’s left out when no wall has paint of its own, and importing a document without it leaves the room’s feature walls as they are.

`footprint` describes a non-rectangular room as a set of grid cells: `cellSize` in meters (one of 0.1, 0.25, 0.5, 1, 2) and `cells` as `[column, row]` pairs from a 0,0 origin.

### Openings

Doors, windows, open sections, and railings are always listed explicitly in `room.openings`.

| Field            | Type                                                    | Description                                                                                                                                                                |
| ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`required     | `string`                                                | Opening id, unique within the room (op\_…).                                                                                                                                |
| `kind`required   | `"window" \| "door" \| "open" \| "railing"`             | "window", "door", "open" (a stretch of wall that isn't there — a cased opening or a room open to the next), or "railing" (a half-height balustrade where a wall would be). |
| `side`required   | `"back" \| "front" \| "left" \| "right"`                | Which wall the opening is on.                                                                                                                                              |
| `edge`           | `number`                                                | Traced-outline edge index for shaped rooms; absent = the 4-side address                                                                                                    |
| `center`required | `number`                                                | Center as a 0–1 fraction along the wall                                                                                                                                    |
| `width`required  | `number`                                                | Opening width, meters                                                                                                                                                      |
| `sill`required   | `number`                                                | Bottom edge above the floor, meters (0 for doors)                                                                                                                          |
| `height`required | `number`                                                | Opening height, meters                                                                                                                                                     |
| `panes`          | `number`                                                | Window panes: omitted/0 = auto, 1 = single sheet, N = N panes. Doors: 0 = no leaf (cased opening)                                                                          |
| `hinge`          | `"start" \| "end"`                                      | Door hinge jamb; windows ignore it                                                                                                                                         |
| `swing`          | `"in" \| "out"`                                         | Door swing; only "out" is stored                                                                                                                                           |
| `leaf`           | `"swing" \| "sliding" \| "bifold" \| "pocket"`          | Door leaf type; omitted = swing, which is never stored                                                                                                                     |
| `leafStyle`      | `"flush" \| "lite" \| "glass" \| "panel" \| "twoPanel"` | Door leaf face; omitted = flush, which is never stored                                                                                                                     |
| `leafColor`      | `string`                                                | Door leaf paint as #rrggbb                                                                                                                                                 |
| `frameColor`     | `string`                                                | Casing/frame paint as #rrggbb; omitted = inherit                                                                                                                           |
| `open`           | `boolean`                                               | Door leaf open; only false is stored                                                                                                                                       |

An explicit empty `openings` array means “no openings”.

## Placements

Each placement has:

| Field       | Type    | Description                                                                                            |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `id`        | integer | Required. Positive, unique within the document. Other placements refer to it (`parentId`).             |
| `catalogId` | string  | Required. The catalog item. Catalog ids are opaque; use the ids the catalog API returns.               |
| `x`, `y`    | number  | Required. Top-left of the footprint, meters.                                                           |
| `item`      | object  | Required. `{ name, w, d }` — a snapshot so the document reads without the catalog. Informational only. |
| `config`    | object  | Optional. The fields below, each present only when set on the piece.                                   |

`item` is never trusted on import: the footprint is recomputed from `catalogId`, `size`, `scale`, and `rotation`.

### Placement config

| Field          | Type       | Description                                                                                                                         |
| -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `rotation`     | `number`   | Facing in degrees: 0 = front toward +y (into the room), 90 = left, 180 = up (−y), 270 = right. Any angle is valid.                  |
| `finish`       | `string`   | Name of one of the catalog item's finishes. Unknown names fall back to the default.                                                 |
| `size`         | `string`   | Name of one of the catalog item's size presets. Unknown names fall back to the default.                                             |
| `mountH`       | `number`   | Wall-mount height above the floor, meters, for wall-snapping items such as a TV.                                                    |
| `elevation`    | `number`   | Free lift above the floor, meters, for a piece with nothing else to rest on.                                                        |
| `on`           | `boolean`  | Powered on, for screens and lights. Only true is written.                                                                           |
| `power`        | `number`   | Dimmer for a light, 0–1. Absent means full.                                                                                         |
| `open`         | `boolean`  | Lid state for lidded items (a laptop). Only false is written.                                                                       |
| `src`          | `string`   | Displayed content for a screen, artwork, or board: an http(s) URL or a small data:image URL.                                        |
| `propParams`   | `object`   | Parameters for a parametric prop (width, height, diagonal, ratio, and so on). Rejected on an item that has none.                    |
| `pileH`        | `number`   | Pile height for a rug, meters.                                                                                                      |
| `fringed`      | `boolean`  | Fringed ends on a rug. Only true is written.                                                                                        |
| `hidden`       | `boolean`  | Hidden from the stage but still part of the room and its bill of materials.                                                         |
| `locked`       | `boolean`  | Locks the piece in place. true and false are both meaningful; absent uses the item's default.                                       |
| `selectable`   | `boolean`  | Whether viewers can pick the piece on share and embed surfaces. true and false are both meaningful; absent uses the item's default. |
| `scale`        | `number`   | Uniform scale. Absent means 1.                                                                                                      |
| `ordered`      | `boolean`  | false leaves a priced piece out of the order and quote.                                                                             |
| `suggested`    | `boolean`  | Shows the piece as a suggestion rather than a committed choice.                                                                     |
| `raised`       | `boolean`  | Sit-stand desk raised to standing. Superseded by raiseT.                                                                            |
| `raiseT`       | `number`   | Sit-stand height, 0 (sitting) to 1 (standing).                                                                                      |
| `doorsOpen`    | `string[]` | Ids of the item's door leaves that are swung open.                                                                                  |
| `artW`         | `number`   | Custom artwork width, meters. Wins over size.                                                                                       |
| `artH`         | `number`   | Custom artwork height, meters. Wins over size.                                                                                      |
| `slotFinishes` | `object`   | Per-part finish overrides keyed by slot (frame, base, textile, …), for manufacturer models that support them.                       |
| `parentId`     | `number`   | Id of another placement in this document that this piece is grouped under or attached to.                                           |
| `attachAt`     | `string`   | The parent's attach point this piece is seated in. Only meaningful with parentId.                                                   |
| `attachT`      | `number`   | Position along a rail attach point, 0–1.                                                                                            |
| `attachments`  | `object[]` | Every seat of a piece that spans two or more parents (a worksurface across two pedestals).                                          |
| `system`       | `object`   | Identifies a manufacturer system assembly. Only meaningful on a group.                                                              |
| `label`        | `string`   | A name given to a group.                                                                                                            |

Anything not listed here is not part of the format: unknown fields anywhere in the document are ignored on import rather than rejected.

## Versioning

* Within a version, only optional fields are added. A v1 reader keeps accepting every v1 document.
* A breaking change bumps `version`. During a migration, Sunny may accept more than one version.
* A document with an unsupported `format` or `version` fails with a message naming the versions that are supported.

## Export and import over the REST API

| Method and path                 | Scope            | Purpose                                            |
| ------------------------------- | ---------------- | -------------------------------------------------- |
| `GET /spaces/{spaceId}/layout`  | `projects:read`  | Export the room’s current layout.                  |
| `POST /spaces/{spaceId}/layout` | `projects:write` | Import a document as a new version of the room.    |
| `POST /plan.svg`                | `projects:read`  | Render a document as a 2D plan SVG. Saves nothing. |

Call them on `https://api.sunnysdk.com` with an OAuth access token or API key carrying the scope — see [OAuth & scopes](/docs/oauth) and the [REST API](/docs/api).

Export

```bash
curl https://api.sunnysdk.com/spaces/spc_8QnZr2kVtL4x/layout \
  -H "Authorization: Bearer $TOKEN"
```

Import

```bash
curl -X POST https://api.sunnysdk.com/spaces/spc_8QnZr2kVtL4x/layout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @layout.json
```

An import never edits an existing version: it saves the document as a new version of the room, and the room takes on the document’s width and depth (unless the document carries a `footprint`, which defines the shape instead). Each placement is resolved against the catalog; one whose `catalogId` doesn’t resolve is dropped and reported, and the rest still import.

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `201`  | Imported; every placement resolved.                                   |
| `207`  | Imported, but some placements were dropped. `itemErrors` lists them.  |
| `400`  | Not imported: the body isn’t JSON, or the document failed validation. |
| `404`  | The space doesn’t exist or isn’t visible to your workspace.           |

201 or 207

```json
{
  "id": "gen_h4Kd9Qe2LmXa",
  "itemErrors": [
    { "index": 3, "catalogId": "itm_retired01", "error": "Unknown catalog item: itm_retired01" }
  ]
}
```

`id` is the new version. `itemErrors[].index` is the position in your `placements` array.

400

```json
{
  "error": "Invalid layout document",
  "details": ["placements.0.x: Invalid input: expected number, received string"]
}
```

`details` lists one message per invalid field, prefixed with its path. A body that isn’t JSON at all returns `{ "error": "Invalid JSON body" }` with no `details`.

## Over MCP

The [MCP server](/docs/mcp) exposes the same operations as `export_layout` (needs `projects:read`) and `import_layout` (needs `projects:write`). They read and write the same format with the same validation and catalog resolution; `import_layout` reports dropped placements per item the same way.

## In an embed

The full studio embed accepts a document over `postMessage` with `load_layout`, and every embeddable room posts its current layout as a `sunny-layout` document. Nothing is saved to a project that way. See [Embeds](/docs/embed).

## Limits

* One room per document; there are no floor-level documents.
* No import/export UI in the app yet — use the API, MCP, or an embed.
* No IFC, GeoJSON, or other CAD formats.