# Sunny API v1

- **OpenAPI Version:** `3.1.0`
- **API Version:** `1.0.0-beta.14`

The versioned Sunny API. `/v1` changes are **additive only**: new endpoints,
new optional request fields, new response fields, new enum values, including
a new error `type` or `code`. A removal is announced with `Deprecation` and
`Sunset` headers at least six months ahead. Operations marked **beta**
(`x-sunny-stability: beta`) may still
change shape; everything else is held to the additive rule by CI.

## TypeScript SDK

`@sunnysdk/client` wraps every operation here in a typed method
(`sunny.quotes.get(id)`), with retries, idempotency keys, pagination and
webhook verification. Install it with `npm install @sunnysdk/client@beta`;
each operation's **@sunnysdk/client** example shows its call, and the
[SDK guide](https://sunnysdk.com/docs/sdk) covers the rest.

## Client contract

Ignore response fields you don't recognise, and handle enum values you
don't recognise (error `type`s and `code`s included). That is what lets
new fields and values ship without a new version.

## Authentication

Send an API key as `x-api-key` (`sunny_wsk_…` workspace or `sunny_sk_…`
personal), or an OAuth 2.1 Bearer token. Cookie sessions and the
first-party shared secret are not accepted on `/v1`. `/v1` is
server-to-server: browsers get no CORS allowance.

## Conventions

- Ids are opaque strings; don't parse them.
- Fields are snake_case. Timestamps are ISO 8601 in UTC.
- A field with no value is omitted, never `null`.
- Lists are `{ data, next_cursor? }`. Pass `next_cursor` back as `cursor`;
  it is omitted on the last page. `limit` is 1-100, default 25.
- Every response carries `X-Request-Id`. Quote it when reporting a problem.

## Errors

Every error is `{ error: { type, code, message, param?, request_id } }`.
The documented `type` values (`invalid_request_error`,
`authentication_error`, `permission_error`, `idempotency_error`,
`rate_limit_error`, `api_error`) are the current set. New types may be
added; clients must handle a `type` they don't recognise. `code` is
specific and grows the same way. Neither is renamed or repurposed.
`param` names the request field at fault when there is one.

## Retries and limits

POST and PATCH accept an `Idempotency-Key` header (1-255 printable ASCII
characters); a retry with the same key and request replays the stored
response with `Idempotent-Replayed: true`.

Requests are limited per owner (per workspace for workspace keys, per user
otherwise): 600 reads and 120 writes per
60 seconds, shared with the unversioned API. A rejection is
`429` with `Retry-After`.

## Contents

**Operations**

- [GET /v1/audit-events](#scalar-operation-get-v1audit-events)
- [GET /v1/catalog/items](#scalar-operation-get-v1catalogitems)
- [GET /v1/catalog/items/{id}](#scalar-operation-get-v1catalogitemsid)
- [GET /v1/customers](#scalar-operation-get-v1customers)
- [POST /v1/customers](#scalar-operation-post-v1customers)
- [DELETE /v1/customers/{id}](#scalar-operation-delete-v1customersid)
- [GET /v1/customers/{id}](#scalar-operation-get-v1customersid)
- [PATCH /v1/customers/{id}](#scalar-operation-patch-v1customersid)
- [GET /v1/discount-tables](#scalar-operation-get-v1discount-tables)
- [GET /v1/discount-tables/{id}](#scalar-operation-get-v1discount-tablesid)
- [GET /v1/floors/{id}](#scalar-operation-get-v1floorsid)
- [PATCH /v1/floors/{id}](#scalar-operation-patch-v1floorsid)
- [GET /v1/floors/{id}/check](#scalar-operation-get-v1floorsidcheck)
- [GET /v1/floors/{id}/rooms](#scalar-operation-get-v1floorsidrooms)
- [POST /v1/floors/{id}/rooms](#scalar-operation-post-v1floorsidrooms)
- [GET /v1/manufacturers/{id}](#scalar-operation-get-v1manufacturersid)
- [GET /v1/projects](#scalar-operation-get-v1projects)
- [POST /v1/projects](#scalar-operation-post-v1projects)
- [GET /v1/projects/{id}](#scalar-operation-get-v1projectsid)
- [PATCH /v1/projects/{id}](#scalar-operation-patch-v1projectsid)
- [GET /v1/projects/{id}/files](#scalar-operation-get-v1projectsidfiles)
- [GET /v1/projects/{id}/floors](#scalar-operation-get-v1projectsidfloors)
- [POST /v1/projects/{id}/floors](#scalar-operation-post-v1projectsidfloors)
- [GET /v1/quotes](#scalar-operation-get-v1quotes)
- [POST /v1/quotes](#scalar-operation-post-v1quotes)
- [POST /v1/quotes/import](#scalar-operation-post-v1quotesimport)
- [DELETE /v1/quotes/{id}](#scalar-operation-delete-v1quotesid)
- [GET /v1/quotes/{id}](#scalar-operation-get-v1quotesid)
- [PATCH /v1/quotes/{id}](#scalar-operation-patch-v1quotesid)
- [GET /v1/quotes/{id}/lines](#scalar-operation-get-v1quotesidlines)
- [POST /v1/quotes/{id}/lines](#scalar-operation-post-v1quotesidlines)
- [DELETE /v1/quotes/{id}/lines/{lineId}](#scalar-operation-delete-v1quotesidlineslineid)
- [PATCH /v1/quotes/{id}/lines/{lineId}](#scalar-operation-patch-v1quotesidlineslineid)
- [GET /v1/quotes/{id}/order](#scalar-operation-get-v1quotesidorder)
- [GET /v1/quotes/{id}/order.sif](#scalar-operation-get-v1quotesidordersif)
- [GET /v1/quotes/{id}/order.xml](#scalar-operation-get-v1quotesidorderxml)
- [DELETE /v1/quotes/{id}/present-link](#scalar-operation-delete-v1quotesidpresent-link)
- [GET /v1/quotes/{id}/present-link](#scalar-operation-get-v1quotesidpresent-link)
- [POST /v1/quotes/{id}/present-link](#scalar-operation-post-v1quotesidpresent-link)
- [POST /v1/quotes/{id}/present-link/send](#scalar-operation-post-v1quotesidpresent-linksend)
- [GET /v1/quotes/{id}/versions](#scalar-operation-get-v1quotesidversions)
- [GET /v1/rooms/{id}](#scalar-operation-get-v1roomsid)
- [PATCH /v1/rooms/{id}](#scalar-operation-patch-v1roomsid)
- [GET /v1/rooms/{id}/layout](#scalar-operation-get-v1roomsidlayout)
- [PUT /v1/rooms/{id}/layout](#scalar-operation-put-v1roomsidlayout)
- [GET /v1/rooms/{id}/versions](#scalar-operation-get-v1roomsidversions)
- [POST /v1/sandbox/reset](#scalar-operation-post-v1sandboxreset)
- [GET /v1/search](#scalar-operation-get-v1search)

**Schemas**

- [AuditEvent](#scalar-schema-auditevent)
- [AuditEventList](#scalar-schema-auditeventlist)
- [CatalogFinish](#scalar-schema-catalogfinish)
- [CatalogItem](#scalar-schema-catalogitem)
- [CatalogItemList](#scalar-schema-catalogitemlist)
- [CatalogPhoto](#scalar-schema-catalogphoto)
- [CatalogPlacement](#scalar-schema-catalogplacement)
- [CatalogSize](#scalar-schema-catalogsize)
- [Customer](#scalar-schema-customer)
- [CustomerList](#scalar-schema-customerlist)
- [Deleted](#scalar-schema-deleted)
- [Dimensions](#scalar-schema-dimensions)
- [DiscountRule](#scalar-schema-discountrule)
- [DiscountTable](#scalar-schema-discounttable)
- [DiscountTableList](#scalar-schema-discounttablelist)
- [DiscountTableRevision](#scalar-schema-discounttablerevision)
- [Error](#scalar-schema-error)
- [Floor](#scalar-schema-floor)
- [FloorCheck](#scalar-schema-floorcheck)
- [FloorIssue](#scalar-schema-floorissue)
- [FloorList](#scalar-schema-floorlist)
- [FloorStructure](#scalar-schema-floorstructure)
- [LayoutDocument](#scalar-schema-layoutdocument)
- [LayoutImportResult](#scalar-schema-layoutimportresult)
- [LayoutPlacement](#scalar-schema-layoutplacement)
- [LayoutPlacementConfig](#scalar-schema-layoutplacementconfig)
- [LayoutRoom](#scalar-schema-layoutroom)
- [Manufacturer](#scalar-schema-manufacturer)
- [Money](#scalar-schema-money)
- [OrderDraft](#scalar-schema-orderdraft)
- [OrderImportLine](#scalar-schema-orderimportline)
- [OrderImportPreflight](#scalar-schema-orderimportpreflight)
- [OrderIssue](#scalar-schema-orderissue)
- [PresentLink](#scalar-schema-presentlink)
- [PresentLinkSendResult](#scalar-schema-presentlinksendresult)
- [Project](#scalar-schema-project)
- [ProjectFile](#scalar-schema-projectfile)
- [ProjectFileList](#scalar-schema-projectfilelist)
- [ProjectList](#scalar-schema-projectlist)
- [ProjectMember](#scalar-schema-projectmember)
- [Quote](#scalar-schema-quote)
- [QuoteImportDryRun](#scalar-schema-quoteimportdryrun)
- [QuoteImportResult](#scalar-schema-quoteimportresult)
- [QuoteLine](#scalar-schema-quoteline)
- [QuoteLineList](#scalar-schema-quotelinelist)
- [QuoteLineOption](#scalar-schema-quotelineoption)
- [QuoteList](#scalar-schema-quotelist)
- [QuoteOrder](#scalar-schema-quoteorder)
- [QuoteTotals](#scalar-schema-quotetotals)
- [QuoteVersion](#scalar-schema-quoteversion)
- [QuoteVersionList](#scalar-schema-quoteversionlist)
- [Rect](#scalar-schema-rect)
- [Room](#scalar-schema-room)
- [RoomFootprint](#scalar-schema-roomfootprint)
- [RoomList](#scalar-schema-roomlist)
- [RoomVersion](#scalar-schema-roomversion)
- [RoomVersionList](#scalar-schema-roomversionlist)
- [SearchFamily](#scalar-schema-searchfamily)
- [SearchProject](#scalar-schema-searchproject)
- [SearchResult](#scalar-schema-searchresult)
- [SearchRoom](#scalar-schema-searchroom)
- [SearchTypical](#scalar-schema-searchtypical)
- [SpaceFootprint](#scalar-schema-spacefootprint)
- [Wainscot](#scalar-schema-wainscot)
- [WallOpening](#scalar-schema-wallopening)
- [WallTrim](#scalar-schema-walltrim)

<a id="scalar-context-global-servers"></a>

## Servers

- **URL:** `https://api.sunnysdk.com`
  - **Description:** Production

## Tags

### projects

A project is one job, usually one building. It holds the floors, and its Library holds the job's photos, documents and 3D models.

### floors

A floor is one storey of a project. Rooms sit on its plate, and the floor check reports rooms that overlap, run off the plate or sit on the building core.

### rooms

A room sits on a floor. Its furniture is the room's layout, which you can read or replace as a sunny-layout document. Every save keeps a version.

### catalog

The furniture Sunny can place and quote: products with their sizes, finishes and photos, and the manufacturers that make them.

### customers

The people and companies a workspace quotes for. Every quote belongs to a customer.

### quotes

A quote prices furniture for a customer, one line per product or charge. Export it as an Order SIF or OFDA XML file, or import one of those as a draft.

### present

A Present link is the URL that shows a quote to the customer. A quote has one active link at a time; revoking it stops the URL working.

### discount-tables

A discount table sets dealer cost: the discount off list price, by manufacturer, catalog, product group or SKU. Reading one needs `quote_costs:read`.

### search

One query across projects, rooms, catalog items, typicals, product families, customers and quotes.

### audit

Who changed what in the workspace: API keys, quotes, customers, discount tables and webhook endpoints.

### sandbox

A sandbox workspace holds test data for building against the API. Resetting it restores the starting customer and discount table.

## Operations

<a id="scalar-operation-get-v1audit-events"></a>

### List audit events

- **Method:** `GET`
- **Path:** `/v1/audit-events`
- **Operation ID:** `listAuditEvents`
- **Tags:** audit

Who changed what in the caller's workspace, newest first: API-key lifecycle, quote, customer, quote-line and discount-table writes, and webhook endpoint changes. Filters are exact matches. Pass `next_cursor` back as `cursor` for the next page.

Allowed for a workspace API key carrying `audit:read`, and for a Bearer token or personal key carrying `audit:read` whose user is an owner or admin of their active workspace.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `audit:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`

  `next_cursor` from the previous page
- **`action`**: `string`, minLength: `1`

  Exact match, e.g. `quote.updated`
- **`target_type`**: `string`, minLength: `1`
- **`target_id`**: `string`, minLength: `1`
- **`actor_kind`**: `string`, possible values: `"user", "api_key", "oauth_client", "system"`
- **`actor_id`**: `string`, minLength: `1`

#### Responses

##### 200 One page of audit events

**Content type:** `application/json`

[AuditEventList](#scalar-schema-auditeventlist)

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "data": [
    {
      "action": "quote.updated",
      "actor": {
        "id": "",
        "kind": "user",
        "user_id": ""
      },
      "created_at": "2026-10-01T15:04:05.000Z",
      "detail": {
        "additionalProperty": null
      },
      "id": "",
      "org_id": "",
      "request_id": "",
      "summary": "",
      "target": {
        "id": "",
        "type": "quote"
      }
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A query parameter is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`audit:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

<a id="scalar-example-2"></a>

**Generated example:**

```json
{
  "error": {
    "code": "parameter_invalid",
    "message": "",
    "param": "limit",
    "request_id": "",
    "type": "invalid_request_error"
  }
}
```

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1catalogitems"></a>

### List catalog items

- **Method:** `GET`
- **Path:** `/v1/catalog/items`
- **Operation ID:** `listCatalogItems`
- **Tags:** catalog

The catalog items you can read, ordered by id. Dealer-only items appear only when your workspace holds an active owner or dealer relationship with their manufacturer. Filters are exact matches and combine with AND; `family` and `sku` ignore case. With `q`, results are a free-text search ordered best match first.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `catalog:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page
- **`manufacturer`**: `string`, minLength: `1`, maxLength: `200`

  Manufacturer id or slug, as `/v1/manufacturers/{id}` takes it. An unknown one matches nothing.
- **`family`**: `string`, minLength: `1`, maxLength: `200`

  Product family, case-insensitive exact match
- **`category`**: `string`, possible values: `"table", "seating", "storage", "accent", "desk", "lighting"`
- **`sku`**: `string`, minLength: `1`, maxLength: `200`

  Manufacturer SKU, case-insensitive exact match
- **`q`**: `string`, minLength: `1`, maxLength: `200`

  Free-text search over id, name, family, SKU and category. Every word must match. Results come best match first instead of by id. Beta.
- **`include`**: `string`, pattern: `^(options|media|placement)(,(options|media|placement))*$`

  Comma-separated optional sections to add to each item: `options` (finishes and sizes), `media` (3D model and product photos), `placement` (what Sunny's layout tools need). Beta.

#### Responses

##### 200 One page of catalog items

**Content type:** `application/json`

[CatalogItemList](#scalar-schema-catalogitemlist)

<a id="scalar-example-3"></a>

**Generated example:**

```json
{
  "data": [
    {
      "agent_note": "",
      "category": "table",
      "description": "",
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "family": "",
      "finishes": [
        {
          "color": "#8a6a4f",
          "material": "",
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "id": "",
      "image_url": "",
      "internal_note": "",
      "list_price": {
        "amount": -9007199254740991,
        "currency": "USD"
      },
      "manufacturer": "",
      "model_number": "",
      "model_takes_finish_color": true,
      "model_url": "",
      "name": "",
      "placement": {
        "color": "",
        "flags": [
          ""
        ],
        "placeholder": true,
        "prop": {
          "defaults": {
            "additionalProperty": null
          },
          "fields": [
            ""
          ],
          "kind": "",
          "schema": {
            "additionalProperty": null
          }
        },
        "seats": -9007199254740991,
        "shape": "rect"
      },
      "plan_symbol": "manufacturer",
      "reference_photos": [
        {
          "license": "",
          "scope": "exact",
          "source": "",
          "url": ""
        }
      ],
      "retired": true,
      "seat_type": "task",
      "sizes": [
        {
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "sku": ""
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A query parameter is invalid (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`catalog:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1catalogitemsid"></a>

### Get a catalog item

- **Method:** `GET`
- **Path:** `/v1/catalog/items/{id}`
- **Operation ID:** `getCatalogItem`
- **Tags:** catalog

One catalog item by id or slug. A retired item still resolves, so a quote line that names it can be looked up; it just no longer appears in the list.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `catalog:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`include`**: `string`, pattern: `^(options|media|placement)(,(options|media|placement))*$`

  Comma-separated optional sections to add to each item: `options` (finishes and sizes), `media` (3D model and product photos), `placement` (what Sunny's layout tools need). Beta.

#### Responses

##### 200 The catalog item

**Content type:** `application/json`

[CatalogItem](#scalar-schema-catalogitem)

A catalog product. Optional sections come with `include`; notes depend on your scopes.

<a id="scalar-example-4"></a>

**Generated example:**

```json
{
  "agent_note": "",
  "category": "table",
  "description": "",
  "dimensions": {
    "depth": 1,
    "height": 1,
    "width": 1
  },
  "family": "",
  "finishes": [
    {
      "color": "#8a6a4f",
      "material": "",
      "name": "",
      "price_adder": {
        "amount": -9007199254740991,
        "currency": "USD"
      }
    }
  ],
  "id": "",
  "image_url": "",
  "internal_note": "",
  "list_price": {
    "amount": -9007199254740991,
    "currency": "USD"
  },
  "manufacturer": "",
  "model_number": "",
  "model_takes_finish_color": true,
  "model_url": "",
  "name": "",
  "placement": {
    "color": "",
    "flags": [
      ""
    ],
    "placeholder": true,
    "prop": {
      "defaults": {
        "additionalProperty": null
      },
      "fields": [
        ""
      ],
      "kind": "",
      "schema": {
        "additionalProperty": null
      }
    },
    "seats": -9007199254740991,
    "shape": "rect"
  },
  "plan_symbol": "manufacturer",
  "reference_photos": [
    {
      "license": "",
      "scope": "exact",
      "source": "",
      "url": ""
    }
  ],
  "retired": true,
  "seat_type": "task",
  "sizes": [
    {
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "name": "",
      "price_adder": {
        "amount": -9007199254740991,
        "currency": "USD"
      }
    }
  ],
  "sku": ""
}
```

##### 400, 401, 403, 404

- `400` \`include\` names an unknown section (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`catalog:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No catalog item you can read has this id or slug (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1customers"></a>

### List customers

- **Method:** `GET`
- **Path:** `/v1/customers`
- **Operation ID:** `listCustomers`
- **Tags:** customers

The workspace's customers, by name. Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of customers

**Content type:** `application/json`

[CustomerList](#scalar-schema-customerlist)

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "email": "",
      "id": "",
      "name": "",
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1customers"></a>

### Create a customer

- **Method:** `POST`
- **Path:** `/v1/customers`
- **Operation ID:** `createCustomer`
- **Tags:** customers

Adds a customer to the workspace. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`name` (required)**: `string`, minLength: `1`, maxLength: `120`
- **`email`**: `string`, maxLength: `200`

<a id="scalar-example-6"></a>

**Generated example:**

```json
{
  "email": "",
  "name": ""
}
```

#### Responses

##### 201 The new customer

**Content type:** `application/json`

[Customer](#scalar-schema-customer)

A customer a workspace quotes for.

<a id="scalar-example-7"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "email": "",
  "id": "",
  "name": "",
  "updated_at": "2026-10-01T15:04:05.000Z"
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1customersid"></a>

### Delete a customer

- **Method:** `DELETE`
- **Path:** `/v1/customers/{id}`
- **Operation ID:** `deleteCustomer`
- **Tags:** customers

Only a customer with no quotes can be deleted; otherwise `409 conflict`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 Deleted

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a delete. Beta.

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "deleted": true,
  "id": ""
}
```

##### 401, 403, 404, 409

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such customer in your workspace (\`not_found\`).
- `409` The customer still has quotes (\`conflict\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1customersid"></a>

### Get a customer

- **Method:** `GET`
- **Path:** `/v1/customers/{id}`
- **Operation ID:** `getCustomer`
- **Tags:** customers

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The customer

**Content type:** `application/json`

[Customer](#scalar-schema-customer)

A customer a workspace quotes for.

[Generated example](#scalar-example-7)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such customer in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1customersid"></a>

### Update a customer

- **Method:** `PATCH`
- **Path:** `/v1/customers/{id}`
- **Operation ID:** `updateCustomer`
- **Tags:** customers

Changes the fields you send; the rest keep their values.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`email`**: `string`, maxLength: `200`

  `""` clears it
- **`name`**: `string`, minLength: `1`, maxLength: `120`

<a id="scalar-example-9"></a>

**Generated example:**

```json
{
  "email": "",
  "name": ""
}
```

#### Responses

##### 200 The updated customer

**Content type:** `application/json`

[Customer](#scalar-schema-customer)

A customer a workspace quotes for.

[Generated example](#scalar-example-7)

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such customer in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1discount-tables"></a>

### List discount tables

- **Method:** `GET`
- **Path:** `/v1/discount-tables`
- **Operation ID:** `listDiscountTables`
- **Tags:** discount-tables

The workspace's discount tables with their revisions and rules. Dealer cost: needs `quote_costs:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quote_costs:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of discount tables

**Content type:** `application/json`

[DiscountTableList](#scalar-schema-discounttablelist)

<a id="scalar-example-10"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "is_default": true,
      "name": "",
      "revisions": [
        {
          "created_at": "2026-10-01T15:04:05.000Z",
          "effective_from": "2026-10-01T15:04:05.000Z",
          "effective_to": "2026-10-01T15:04:05.000Z",
          "id": "",
          "label": "",
          "rules": [
            {
              "buy_percents": [
                1
              ],
              "id": "",
              "match_type": "manufacturer",
              "match_value": "",
              "priority": -9007199254740991,
              "sell_method": "markup_percent",
              "sell_value": 1
            }
          ]
        }
      ]
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A query parameter is invalid (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quote_costs:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1discount-tablesid"></a>

### Get a discount table

- **Method:** `GET`
- **Path:** `/v1/discount-tables/{id}`
- **Operation ID:** `getDiscountTable`
- **Tags:** discount-tables

One table with its revisions and rules. Needs `quote_costs:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quote_costs:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The discount table

**Content type:** `application/json`

[DiscountTable](#scalar-schema-discounttable)

A workspace's dealer discount table: dealer cost, so it needs `quote_costs:read`. Beta.

<a id="scalar-example-11"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "id": "",
  "is_default": true,
  "name": "",
  "revisions": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "effective_from": "2026-10-01T15:04:05.000Z",
      "effective_to": "2026-10-01T15:04:05.000Z",
      "id": "",
      "label": "",
      "rules": [
        {
          "buy_percents": [
            1
          ],
          "id": "",
          "match_type": "manufacturer",
          "match_value": "",
          "priority": -9007199254740991,
          "sell_method": "markup_percent",
          "sell_value": 1
        }
      ]
    }
  ]
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quote_costs:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such discount table in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1floorsid"></a>

### Get a floor

- **Method:** `GET`
- **Path:** `/v1/floors/{id}`
- **Operation ID:** `getFloor`
- **Tags:** floors

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The floor

**Content type:** `application/json`

[Floor](#scalar-schema-floor)

One storey of a project. Beta.

<a id="scalar-example-12"></a>

**Generated example:**

```json
{
  "budget": 0,
  "depth": 1,
  "floor_color": "",
  "floor_rotation": 0,
  "floor_type": "tile",
  "id": "",
  "name": "",
  "page_color": "",
  "project_id": "",
  "room_ids": [
    ""
  ],
  "structure": {
    "circulation": [
      {
        "depth": 1,
        "width": 1,
        "x": 1,
        "y": 1
      }
    ],
    "core": {
      "depth": 1,
      "width": 1,
      "x": 1,
      "y": 1
    },
    "entry": {
      "position": 1,
      "side": "n"
    },
    "facade": [
      "n"
    ]
  },
  "target_headcount": 0,
  "wall_color": "",
  "width": 1
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such floor in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1floorsid"></a>

### Update a floor

- **Method:** `PATCH`
- **Path:** `/v1/floors/{id}`
- **Operation ID:** `updateFloor`
- **Tags:** floors

Changes the fields you send; the rest keep their values. A plate change that would leave a room off the plate is refused with `409 conflict`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`budget`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  The floor's furniture budget, in whole units of the workspace currency
- **`depth`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Plate depth, meters
- **`name`**: `string`, minLength: `1`, maxLength: `120`
- **`target_headcount`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  How many people the floor should seat
- **`width`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Plate width, meters. Refused (`409 conflict`) when it would leave a room off the plate.

<a id="scalar-example-13"></a>

**Generated example:**

```json
{
  "budget": 0,
  "depth": 1,
  "name": "",
  "target_headcount": 0,
  "width": 1
}
```

#### Responses

##### 200 The updated floor

**Content type:** `application/json`

[Floor](#scalar-schema-floor)

One storey of a project. Beta.

[Generated example](#scalar-example-12)

##### 400, 401, 403, 404, 409

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such floor in your workspace (\`not_found\`).
- `409` Refused by the floor check (\`conflict\`): the room would overlap another room, reach off the plate or stand on the building core. The message names the problem.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1floorsidcheck"></a>

### Check a floor

- **Method:** `GET`
- **Path:** `/v1/floors/{id}/check`
- **Operation ID:** `getFloorCheck`
- **Tags:** floors

Checks the floor's rooms against each other, the plate and the building core. `problems` are real faults (rooms overlapping, off the plate or on the core), each naming the rooms involved and usually a fix; `notes` are judgement calls.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The floor check

**Content type:** `application/json`

[FloorCheck](#scalar-schema-floorcheck)

How the rooms on a floor fit the plate and each other. Beta.

<a id="scalar-example-14"></a>

**Generated example:**

```json
{
  "notes": [
    {
      "fix": "",
      "message": "",
      "room_ids": [
        ""
      ],
      "rule": ""
    }
  ],
  "problems": [
    {
      "fix": "",
      "message": "",
      "room_ids": [
        ""
      ],
      "rule": ""
    }
  ],
  "status": "ok",
  "summary": ""
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such floor in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1floorsidrooms"></a>

### List a floor's rooms

- **Method:** `GET`
- **Path:** `/v1/floors/{id}/rooms`
- **Operation ID:** `listRooms`
- **Tags:** rooms

Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of rooms

**Content type:** `application/json`

[RoomList](#scalar-schema-roomlist)

<a id="scalar-example-15"></a>

**Generated example:**

```json
{
  "data": [
    {
      "brief": "",
      "depth": 1,
      "floor_id": "",
      "floor_rotation": 0,
      "footprint": {
        "cell_size": 1,
        "cells": [
          [
            -9007199254740991,
            -9007199254740991
          ]
        ]
      },
      "height": 1,
      "hide_room": true,
      "id": "",
      "name": "",
      "target_seats": -9007199254740991,
      "version_count": 0,
      "wainscot": {
        "color": "",
        "height": 1,
        "sides": [
          "back"
        ]
      },
      "wall_trim": {
        "baseboard": {
          "color": "",
          "style": "classic"
        },
        "chair": {
          "color": "",
          "height": 1
        },
        "crown": {
          "color": "",
          "style": "simple"
        },
        "picture": {
          "color": "",
          "drop": 1
        }
      },
      "width": 1,
      "x": 1,
      "y": 1
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such floor in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1floorsidrooms"></a>

### Add a room to a floor

- **Method:** `POST`
- **Path:** `/v1/floors/{id}/rooms`
- **Operation ID:** `createRoom`
- **Tags:** rooms

Without `x` and `y` the room takes the first clear spot on the floor. A position where the room would overlap another room, reach off the plate or stand on the building core is refused with `409 conflict`. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`name` (required)**: `string`, minLength: `1`, maxLength: `120`
- **`depth`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior depth, meters
- **`height`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Wall height, meters
- **`target_seats`**: `integer`, minimum: `0`, maximum: `9007199254740991`
- **`width`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior width, meters
- **`x`**: `number`, minimum: `0`

  Left edge, meters. Send with `y`; without both, the room takes the first clear spot.
- **`y`**: `number`, minimum: `0`

  Top edge, meters

<a id="scalar-example-16"></a>

**Generated example:**

```json
{
  "depth": 1,
  "height": 1,
  "name": "",
  "target_seats": 0,
  "width": 1,
  "x": 0,
  "y": 0
}
```

#### Responses

##### 201 The new room

**Content type:** `application/json`

[Room](#scalar-schema-room)

A room on a floor. Its furniture is the room's layout (`/v1/rooms/{id}/layout`). Beta.

<a id="scalar-example-17"></a>

**Generated example:**

```json
{
  "brief": "",
  "depth": 1,
  "floor_id": "",
  "floor_rotation": 0,
  "footprint": {
    "cell_size": 1,
    "cells": [
      [
        -9007199254740991,
        -9007199254740991
      ]
    ]
  },
  "height": 1,
  "hide_room": true,
  "id": "",
  "name": "",
  "target_seats": -9007199254740991,
  "version_count": 0,
  "wainscot": {
    "color": "",
    "height": 1,
    "sides": [
      "back"
    ]
  },
  "wall_trim": {
    "baseboard": {
      "color": "",
      "style": "classic"
    },
    "chair": {
      "color": "",
      "height": 1
    },
    "crown": {
      "color": "",
      "style": "simple"
    },
    "picture": {
      "color": "",
      "drop": 1
    }
  },
  "width": 1,
  "x": 1,
  "y": 1
}
```

##### 400, 401, 403, 404, 409

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such floor in your workspace (\`not_found\`).
- `409` Refused by the floor check (\`conflict\`): the room would overlap another room, reach off the plate or stand on the building core. The message names the problem.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1manufacturersid"></a>

### Get a manufacturer

- **Method:** `GET`
- **Path:** `/v1/manufacturers/{id}`
- **Operation ID:** `getManufacturer`
- **Tags:** catalog

A manufacturer's public profile by id or slug, with counts over the catalog items you can read. List those items with `GET /v1/catalog/items?manufacturer={id}`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `catalog:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The manufacturer

**Content type:** `application/json`

[Manufacturer](#scalar-schema-manufacturer)

A manufacturer's public profile. Counts cover only the catalog items you can read. Beta.

<a id="scalar-example-18"></a>

**Generated example:**

```json
{
  "description": "",
  "families": [
    {
      "item_count": -9007199254740991,
      "name": ""
    }
  ],
  "id": "",
  "item_count": -9007199254740991,
  "logo_url": "",
  "name": "",
  "slug": "",
  "website_url": ""
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`catalog:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such manufacturer (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1projects"></a>

### List projects

- **Method:** `GET`
- **Path:** `/v1/projects`
- **Operation ID:** `listProjects`
- **Tags:** projects

The workspace's projects (archived ones left out). Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of projects

**Content type:** `application/json`

[ProjectList](#scalar-schema-projectlist)

<a id="scalar-example-19"></a>

**Generated example:**

```json
{
  "data": [
    {
      "address": "",
      "floor_ids": [
        ""
      ],
      "id": "",
      "live_editing": true,
      "members": [
        {
          "role": "owner",
          "user_id": ""
        }
      ],
      "name": "",
      "pinned_at": "2026-10-01T15:04:05.000Z",
      "status": ""
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1projects"></a>

### Create a project

- **Method:** `POST`
- **Path:** `/v1/projects`
- **Operation ID:** `createProject`
- **Tags:** projects

Adds a project to the workspace. Add floors with `POST /v1/projects/{id}/floors`. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`name` (required)**: `string`, minLength: `1`, maxLength: `120`
- **`address`**: `string`, maxLength: `200`
- **`status`**: `string`, maxLength: `200`

  Defaults to `Active`

<a id="scalar-example-20"></a>

**Generated example:**

```json
{
  "address": "",
  "name": "",
  "status": ""
}
```

#### Responses

##### 201 The new project

**Content type:** `application/json`

[Project](#scalar-schema-project)

A project: a building or job. Beta.

<a id="scalar-example-21"></a>

**Generated example:**

```json
{
  "address": "",
  "floor_ids": [
    ""
  ],
  "id": "",
  "live_editing": true,
  "members": [
    {
      "role": "owner",
      "user_id": ""
    }
  ],
  "name": "",
  "pinned_at": "2026-10-01T15:04:05.000Z",
  "status": ""
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1projectsid"></a>

### Get a project

- **Method:** `GET`
- **Path:** `/v1/projects/{id}`
- **Operation ID:** `getProject`
- **Tags:** projects

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The project

**Content type:** `application/json`

[Project](#scalar-schema-project)

A project: a building or job. Beta.

[Generated example](#scalar-example-21)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such project in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1projectsid"></a>

### Update a project

- **Method:** `PATCH`
- **Path:** `/v1/projects/{id}`
- **Operation ID:** `updateProject`
- **Tags:** projects

Changes the fields you send; the rest keep their values.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`address`**: `string`, maxLength: `200`
- **`name`**: `string`, minLength: `1`, maxLength: `120`
- **`status`**: `string`, maxLength: `200`

<a id="scalar-example-22"></a>

**Generated example:**

```json
{
  "address": "",
  "name": "",
  "status": ""
}
```

#### Responses

##### 200 The updated project

**Content type:** `application/json`

[Project](#scalar-schema-project)

A project: a building or job. Beta.

[Generated example](#scalar-example-21)

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such project in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1projectsidfiles"></a>

### List a project's files

- **Method:** `GET`
- **Path:** `/v1/projects/{id}/files`
- **Operation ID:** `listProjectFiles`
- **Tags:** projects

The photos, documents and 3D models in the project's Library, project-wide and each room's own, newest first. Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of files

**Content type:** `application/json`

[ProjectFileList](#scalar-schema-projectfilelist)

<a id="scalar-example-23"></a>

**Generated example:**

```json
{
  "data": [
    {
      "content_type": "",
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "kind": "image",
      "name": "",
      "room_id": "",
      "size": 0,
      "url": ""
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such project in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1projectsidfloors"></a>

### List a project's floors

- **Method:** `GET`
- **Path:** `/v1/projects/{id}/floors`
- **Operation ID:** `listFloors`
- **Tags:** floors

In the project's order. Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of floors

**Content type:** `application/json`

[FloorList](#scalar-schema-floorlist)

<a id="scalar-example-24"></a>

**Generated example:**

```json
{
  "data": [
    {
      "budget": 0,
      "depth": 1,
      "floor_color": "",
      "floor_rotation": 0,
      "floor_type": "tile",
      "id": "",
      "name": "",
      "page_color": "",
      "project_id": "",
      "room_ids": [
        ""
      ],
      "structure": {
        "circulation": [
          {
            "depth": 1,
            "width": 1,
            "x": 1,
            "y": 1
          }
        ],
        "core": {
          "depth": 1,
          "width": 1,
          "x": 1,
          "y": 1
        },
        "entry": {
          "position": 1,
          "side": "n"
        },
        "facade": [
          "n"
        ]
      },
      "target_headcount": 0,
      "wall_color": "",
      "width": 1
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such project in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1projectsidfloors"></a>

### Add a floor to a project

- **Method:** `POST`
- **Path:** `/v1/projects/{id}/floors`
- **Operation ID:** `createFloor`
- **Tags:** floors

Without `width` and `depth` the floor gets the default plate. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`name` (required)**: `string`, minLength: `1`, maxLength: `120`
- **`budget`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  The floor's furniture budget, in whole units of the workspace currency
- **`depth`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Plate depth, meters
- **`target_headcount`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  How many people the floor should seat
- **`width`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Plate width, meters. Send with `depth`; both default together.

<a id="scalar-example-25"></a>

**Generated example:**

```json
{
  "budget": 0,
  "depth": 1,
  "name": "",
  "target_headcount": 0,
  "width": 1
}
```

#### Responses

##### 201 The new floor

**Content type:** `application/json`

[Floor](#scalar-schema-floor)

One storey of a project. Beta.

[Generated example](#scalar-example-12)

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such project in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotes"></a>

### List quotes

- **Method:** `GET`
- **Path:** `/v1/quotes`
- **Operation ID:** `listQuotes`
- **Tags:** quotes

The workspace's quotes, newest first. Cost fields (`buy_unit`, `applied_rule_id`, `totals.buy_total`, `totals.margin`, `totals.margin_percent`, `discount_table_revision_id`) are present only when the caller holds `quote_costs:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of quotes

**Content type:** `application/json`

[QuoteList](#scalar-schema-quotelist)

<a id="scalar-example-26"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "currency": "USD",
      "customer_id": "",
      "discount_table_revision_id": "",
      "id": "",
      "name": "",
      "number": "Q-000123",
      "status": "draft",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      },
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1quotes"></a>

### Create a quote

- **Method:** `POST`
- **Path:** `/v1/quotes`
- **Operation ID:** `createQuote`
- **Tags:** quotes

Creates a draft quote for a customer, priced by the workspace's default discount table. The quote takes the workspace currency. Emits `quote.created`. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`customer_id` (required)**: `string`, minLength: `1`

  A customer in the caller's workspace
- **`name` (required)**: `string`, minLength: `1`, maxLength: `120`

<a id="scalar-example-27"></a>

**Generated example:**

```json
{
  "customer_id": "",
  "name": ""
}
```

#### Responses

##### 201 The new quote

**Content type:** `application/json`

[Quote](#scalar-schema-quote)

A quote. Lines are a sub-resource (`/v1/quotes/{id}/lines`), not embedded.

<a id="scalar-example-28"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "currency": "USD",
  "customer_id": "",
  "discount_table_revision_id": "",
  "id": "",
  "name": "",
  "number": "Q-000123",
  "status": "draft",
  "totals": {
    "buy_total": -9007199254740991,
    "line_count": -9007199254740991,
    "list_total": -9007199254740991,
    "margin": -9007199254740991,
    "margin_percent": 1,
    "sell_total": -9007199254740991
  },
  "updated_at": "2026-10-01T15:04:05.000Z"
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such customer in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1quotesimport"></a>

### Import an order file as a draft quote

- **Method:** `POST`
- **Path:** `/v1/quotes/import`
- **Operation ID:** `importQuoteOrder`
- **Tags:** quotes

Reads a configured-order file, Order SIF or OFDA XML (detected by content, never the file name), and creates a draft quote from it. Send the file as the raw body (`text/plain` or `application/xml`, options in the query string) or as JSON `{ file, customer_id, … }`.

The file is first checked against the manufacturer catalogs loaded for your account (the same check as order preflight), then each line is matched by SKU to one quotable catalog item and priced from the catalog list and the quote's discount table, like `POST /v1/quotes/{id}/lines`. A line whose SKU matches no item, or more than one, is skipped and reported in `preflight`, never a failed request. The file's options are kept on the line as given.

`dry_run=true` answers `200` with the draft and the report and persists nothing. Otherwise the answer is `201` with the quote and the report, and `quote.created` is emitted once, after the lines exist. Needs `quotes:write` and `orders:write`; `discount_table_id` also needs `quote_costs:read`. Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write, orders:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`dry_run`**: `string`, possible values: `"true", "false"`

  `true`: read and check the file, persist nothing
- **`customer_id`**: `string`, minLength: `1`, maxLength: `80`

  For a raw (`text/plain`, `application/xml`) body: the customer to quote. Required unless `dry_run=true`. A JSON body's `customer_id` wins.
- **`discount_table_id`**: `string`, minLength: `1`, maxLength: `80`

  For a raw body: the discount table to price with. Needs `quote_costs:read`.
- **`name`**: `string`, minLength: `1`, maxLength: `120`

  For a raw body: quote name

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`file` (required)**: `string`, minLength: `1`

  The order file's text: Order SIF or OFDA XML, detected by content. Up to 2 MB.
- **`customer_id`**: `string`, minLength: `1`, maxLength: `80`

  The customer to quote. Required unless `dry_run=true`.
- **`discount_table_id`**: `string`, minLength: `1`, maxLength: `80`

  The discount table to price with (its latest revision); defaults to the workspace's default table. Needs `quote_costs:read`.
- **`filename`**: `string`, minLength: `1`, maxLength: `200`

  The file's name, for messages and the default quote name only
- **`name`**: `string`, minLength: `1`, maxLength: `120`

  Quote name. Defaults to the OFDA project title or PO number, then `filename`, then "Imported order".

<a id="scalar-example-29"></a>

**Generated example:**

```json
{
  "customer_id": "",
  "discount_table_id": "",
  "file": "",
  "filename": "",
  "name": ""
}
```

**Content type:** `application/xml`

`string`

OFDA XML purchase order

<a id="scalar-example-30"></a>

**Generated example:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root></root>
```

**Content type:** `text/plain`

`string`

Order SIF or OFDA XML text

<a id="scalar-example-31"></a>

**Generated example:**

```json
""
```

#### Responses

##### 200 Dry run: nothing persisted

**Content type:** `application/json`

[QuoteImportDryRun](#scalar-schema-quoteimportdryrun)

A dry run: nothing was persisted. Beta.

<a id="scalar-example-32"></a>

**Generated example:**

```json
{
  "draft": {
    "format": "sif",
    "lines": [
      {
        "catalog_code": "",
        "description": "",
        "list_unit": -9007199254740991,
        "manufacturer_code": "",
        "options": [
          {
            "code": "",
            "description": "",
            "group": "",
            "placeholder": true,
            "price_adder": -9007199254740991
          }
        ],
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ]
  },
  "preflight": {
    "catalogs": [
      {
        "key": "",
        "label": ""
      }
    ],
    "format": "sif",
    "issues": [
      {
        "actual": "",
        "check": "file",
        "code": "sku_not_found",
        "expected": "",
        "group": "",
        "keys": [
          ""
        ],
        "message": "",
        "option": "",
        "severity": "error"
      }
    ],
    "lines": [
      {
        "catalog_check": "ok",
        "catalog_item_id": "",
        "importable": true,
        "issues": [
          {
            "actual": "",
            "check": "file",
            "code": "sku_not_found",
            "expected": "",
            "group": "",
            "keys": [
              ""
            ],
            "message": "",
            "option": "",
            "severity": "error"
          }
        ],
        "line_id": "",
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ],
    "status": "pass",
    "summary": {
      "catalog_checked": -9007199254740991,
      "errors": -9007199254740991,
      "importable": -9007199254740991,
      "lines": -9007199254740991,
      "skipped": -9007199254740991,
      "warnings": -9007199254740991
    }
  }
}
```

##### 201 The new draft quote

**Content type:** `application/json`

[QuoteImportResult](#scalar-schema-quoteimportresult)

A persisted import. Beta.

<a id="scalar-example-33"></a>

**Generated example:**

```json
{
  "preflight": {
    "catalogs": [
      {
        "key": "",
        "label": ""
      }
    ],
    "format": "sif",
    "issues": [
      {
        "actual": "",
        "check": "file",
        "code": "sku_not_found",
        "expected": "",
        "group": "",
        "keys": [
          ""
        ],
        "message": "",
        "option": "",
        "severity": "error"
      }
    ],
    "lines": [
      {
        "catalog_check": "ok",
        "catalog_item_id": "",
        "importable": true,
        "issues": [
          {
            "actual": "",
            "check": "file",
            "code": "sku_not_found",
            "expected": "",
            "group": "",
            "keys": [
              ""
            ],
            "message": "",
            "option": "",
            "severity": "error"
          }
        ],
        "line_id": "",
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ],
    "status": "pass",
    "summary": {
      "catalog_checked": -9007199254740991,
      "errors": -9007199254740991,
      "importable": -9007199254740991,
      "lines": -9007199254740991,
      "skipped": -9007199254740991,
      "warnings": -9007199254740991
    }
  },
  "quote": {
    "created_at": "2026-10-01T15:04:05.000Z",
    "currency": "USD",
    "customer_id": "",
    "discount_table_revision_id": "",
    "id": "",
    "name": "",
    "number": "Q-000123",
    "status": "draft",
    "totals": {
      "buy_total": -9007199254740991,
      "line_count": -9007199254740991,
      "list_total": -9007199254740991,
      "margin": -9007199254740991,
      "margin_percent": 1,
      "sell_total": -9007199254740991
    },
    "updated_at": "2026-10-01T15:04:05.000Z"
  }
}
```

##### 400, 401, 403, 404, 413

- `400` The file isn't readable SIF or OFDA XML or holds no lines (\`order_file_invalid\`, \`param: file\`), or a field is missing or invalid (\`parameter_missing\`, \`parameter_invalid\`, \`body_malformed\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` and \`orders:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such customer or discount table in your workspace (\`not_found\`, \`param\` names it).
- `413` The file is larger than 2 MB (\`order_file_too_large\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1quotesid"></a>

### Delete a quote

- **Method:** `DELETE`
- **Path:** `/v1/quotes/{id}`
- **Operation ID:** `deleteQuote`
- **Tags:** quotes

Deletes the quote and its lines. Emits `quote.deleted`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 Deleted

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a delete. Beta.

[Generated example](#scalar-example-8)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesid"></a>

### Get a quote

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}`
- **Operation ID:** `getQuote`
- **Tags:** quotes

The quote and its totals; lines are at `/v1/quotes/{id}/lines`. Cost fields (`buy_unit`, `applied_rule_id`, `totals.buy_total`, `totals.margin`, `totals.margin_percent`, `discount_table_revision_id`) are present only when the caller holds `quote_costs:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The quote

**Content type:** `application/json`

[Quote](#scalar-schema-quote)

A quote. Lines are a sub-resource (`/v1/quotes/{id}/lines`), not embedded.

[Generated example](#scalar-example-28)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1quotesid"></a>

### Update a quote

- **Method:** `PATCH`
- **Path:** `/v1/quotes/{id}`
- **Operation ID:** `updateQuote`
- **Tags:** quotes

Renames the quote or moves its status. `draft` → `presented` snapshots a version, points the Present link at it and emits `quote.presented`; other changes emit `quote.updated`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`name`**: `string`, minLength: `1`, maxLength: `120`
- **`status`**: `string`, possible values: `"draft", "presented", "archived"`

  `draft` → `presented` snapshots a version, points the Present link at it and emits `quote.presented`. `accepted` can't be set yet.

<a id="scalar-example-34"></a>

**Generated example:**

```json
{
  "name": "",
  "status": "draft"
}
```

#### Responses

##### 200 The updated quote

**Content type:** `application/json`

[Quote](#scalar-schema-quote)

A quote. Lines are a sub-resource (`/v1/quotes/{id}/lines`), not embedded.

[Generated example](#scalar-example-28)

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidlines"></a>

### List a quote's lines

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/lines`
- **Operation ID:** `listQuoteLines`
- **Tags:** quotes

In quote order. Cost fields (`buy_unit`, `applied_rule_id`, `totals.buy_total`, `totals.margin`, `totals.margin_percent`, `discount_table_revision_id`) are present only when the caller holds `quote_costs:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of lines

**Content type:** `application/json`

[QuoteLineList](#scalar-schema-quotelinelist)

<a id="scalar-example-35"></a>

**Generated example:**

```json
{
  "data": [
    {
      "applied_rule_id": "",
      "buy_unit": -9007199254740991,
      "catalog_item_id": "",
      "description": "",
      "id": "",
      "kind": "catalog",
      "list_unit": -9007199254740991,
      "options": [
        {
          "code": "",
          "description": "",
          "group": "",
          "price_adder": -9007199254740991
        }
      ],
      "position": -9007199254740991,
      "qty": 1,
      "quote_id": "",
      "sell_unit": -9007199254740991,
      "sku": ""
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1quotesidlines"></a>

### Add a line

- **Method:** `POST`
- **Path:** `/v1/quotes/{id}/lines`
- **Operation ID:** `createQuoteLine`
- **Tags:** quotes

A catalog line names its product by `sku` (plus `manufacturer` when the SKU exists at more than one) or by `catalog_item_id`; the server prices it from the catalog list price and the quote's discount table. Change the price only through `override`; writing `override.buy_percents` needs `quote_costs:read`. An ad-hoc line (`kind: "adhoc"`) takes `description` and `sell_unit`, and optionally `buy_unit` (needs `quote_costs:read`). An unknown SKU is `400 sku_not_found`; an ambiguous one is `409 sku_ambiguous`. Emits `quote.updated` (`line_added`). Send an `Idempotency-Key` to make a retry safe.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`buy_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

  Ad-hoc lines: your cost per piece; defaults to `sell_unit`. Needs `quote_costs:read`. Integer, in minor units of the quote's `currency`.
- **`catalog_item_id`**: `string`, minLength: `1`, maxLength: `80`
- **`description`**: `string`, minLength: `1`, maxLength: `200`

  Ad-hoc lines: the printed text
- **`kind`**: `string`, possible values: `"catalog", "adhoc"`

  `catalog` (default): name the product with `sku` or `catalog_item_id`; the server prices it. `adhoc`: a typed-in charge with `description` and `sell_unit`.
- **`manufacturer`**: `string`, minLength: `1`, maxLength: `120`

  Narrows `sku` to one manufacturer (case-insensitive name match)
- **`options`**: `array`, maxItems: `100`

  Selected options, stored as given; not repriced. Beta.

  **Items:**
  - **`code` (required)**: `string`, minLength: `1`, maxLength: `80`

    Manufacturer option code
  - **`description`**: `string`, maxLength: `200`
  - **`group`**: `string`, maxLength: `200`
  - **`price_adder`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Per piece, in minor units of the quote's `currency`
- **`override`**: `object`

  The only way to change a catalog line's price. Send `{}` to drop a sell override. A caller without `quote_costs:read` can't see or change a buy override; one already on the line is kept.
  - **`buy_percents`**: `array`, maxItems: `10`

    Replaces the matched rule's buy discount chain. Writing it needs `quote_costs:read`.

    **Items:**

    `number`, minimum: `0`, maximum: `100`
  - **`sell_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

    Customer price per piece, replacing the rule's sell method. Integer, in minor units of the quote's `currency`.
- **`qty`**: `integer`, minimum: `1`, maximum: `9999`

  Defaults to 1
- **`sell_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

  Ad-hoc lines: what the customer pays per piece. Integer, in minor units of the quote's `currency`.
- **`sku`**: `string`, minLength: `1`, maxLength: `120`

  Manufacturer SKU. Add `manufacturer` when the SKU exists at more than one.

<a id="scalar-example-36"></a>

**Generated example:**

```json
{
  "buy_unit": 0,
  "catalog_item_id": "",
  "description": "",
  "kind": "catalog",
  "manufacturer": "",
  "options": [
    {
      "code": "",
      "description": "",
      "group": "",
      "price_adder": -9007199254740991
    }
  ],
  "override": {
    "buy_percents": [
      0
    ],
    "sell_unit": 0
  },
  "qty": 1,
  "sell_unit": 0,
  "sku": ""
}
```

#### Responses

##### 201 The new line

**Content type:** `application/json`

[QuoteLine](#scalar-schema-quoteline)

One priced row on a quote.

<a id="scalar-example-37"></a>

**Generated example:**

```json
{
  "applied_rule_id": "",
  "buy_unit": -9007199254740991,
  "catalog_item_id": "",
  "description": "",
  "id": "",
  "kind": "catalog",
  "list_unit": -9007199254740991,
  "options": [
    {
      "code": "",
      "description": "",
      "group": "",
      "price_adder": -9007199254740991
    }
  ],
  "position": -9007199254740991,
  "qty": 1,
  "quote_id": "",
  "sell_unit": -9007199254740991,
  "sku": ""
}
```

##### 400, 401, 403, 404, 409

- `400` A request field is invalid (\`parameter_invalid\`, \`parameter_missing\`), the SKU or catalog item is unknown (\`sku_not_found\`, \`catalog_item_not_found\`), or the item isn't quotable (\`bad_request\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).
- `409` The SKU matches more than one quotable item (\`sku_ambiguous\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1quotesidlineslineid"></a>

### Remove a line

- **Method:** `DELETE`
- **Path:** `/v1/quotes/{id}/lines/{lineId}`
- **Operation ID:** `deleteQuoteLine`
- **Tags:** quotes

Emits `quote.updated` (`line_removed`).

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`
- **`lineId` (required)**: `string`

#### Responses

##### 200 Deleted

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a delete. Beta.

[Generated example](#scalar-example-8)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote, or no such line on it (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1quotesidlineslineid"></a>

### Update a line

- **Method:** `PATCH`
- **Path:** `/v1/quotes/{id}/lines/{lineId}`
- **Operation ID:** `updateQuoteLine`
- **Tags:** quotes

Changes the fields you send and reprices the line. Catalog lines take `qty`, `options` and `override`; ad-hoc lines take `description`, `qty`, `sell_unit`, `buy_unit` and `options`. Writing `override.buy_percents` or `buy_unit` needs `quote_costs:read`; without it, a buy override already on the line is kept. Emits `quote.updated` (`line_updated`).

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`
- **`lineId` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`buy_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

  Ad-hoc lines only. Needs `quote_costs:read`. Integer, in minor units of the quote's `currency`.
- **`description`**: `string`, minLength: `1`, maxLength: `200`

  Ad-hoc lines only
- **`options`**: `array`, maxItems: `100`

  Replaces the selected options. Beta.

  **Items:**
  - **`code` (required)**: `string`, minLength: `1`, maxLength: `80`

    Manufacturer option code
  - **`description`**: `string`, maxLength: `200`
  - **`group`**: `string`, maxLength: `200`
  - **`price_adder`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Per piece, in minor units of the quote's `currency`
- **`override`**: `object`

  The only way to change a catalog line's price. Send `{}` to drop a sell override. A caller without `quote_costs:read` can't see or change a buy override; one already on the line is kept.
  - **`buy_percents`**: `array`, maxItems: `10`

    Replaces the matched rule's buy discount chain. Writing it needs `quote_costs:read`.

    **Items:**

    `number`, minimum: `0`, maximum: `100`
  - **`sell_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

    Customer price per piece, replacing the rule's sell method. Integer, in minor units of the quote's `currency`.
- **`qty`**: `integer`, minimum: `1`, maximum: `9999`
- **`sell_unit`**: `integer`, minimum: `0`, maximum: `1000000000`

  Ad-hoc lines only. Integer, in minor units of the quote's `currency`.

<a id="scalar-example-38"></a>

**Generated example:**

```json
{
  "buy_unit": 0,
  "description": "",
  "options": [
    {
      "code": "",
      "description": "",
      "group": "",
      "price_adder": -9007199254740991
    }
  ],
  "override": {
    "buy_percents": [
      0
    ],
    "sell_unit": 0
  },
  "qty": 1,
  "sell_unit": 0
}
```

#### Responses

##### 200 The updated line

**Content type:** `application/json`

[QuoteLine](#scalar-schema-quoteline)

One priced row on a quote.

[Generated example](#scalar-example-37)

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote, or no such line on it (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidorder"></a>

### Get a quote's order

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/order`
- **Operation ID:** `getQuoteOrder`
- **Tags:** quotes

The order the quote produces, as the order form prints it: list and customer prices, never dealer cost. Ad-hoc charges are footnoted, not ordered. `?version=n` builds from that presented version; absent, from the presented version if the quote has one, else from the live lines, so the file matches what the customer saw. The order file itself is at `order.sif` (Order SIF) and `order.xml` (OFDA XML).

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`version`**: `integer`, minimum: `1`, maximum: `9007199254740991`

  A version number from `/v1/quotes/{id}/versions`. Absent: the presented version if there is one, else the live lines.

#### Responses

##### 200 The order

**Content type:** `application/json`

[QuoteOrder](#scalar-schema-quoteorder)

The order a quote produces, as the order form prints it: list and customer prices, never dealer cost. Beta.

<a id="scalar-example-39"></a>

**Generated example:**

```json
{
  "currency": "USD",
  "customer_name": "",
  "date": "",
  "footnotes": [
    ""
  ],
  "lines": [
    {
      "amount": -9007199254740991,
      "dims": "",
      "kind": "catalog",
      "list_unit": -9007199254740991,
      "n": -9007199254740991,
      "name": "",
      "part": "",
      "qty": -9007199254740991,
      "room": "",
      "sell_unit": -9007199254740991
    }
  ],
  "list_total": -9007199254740991,
  "notes": "",
  "number": "",
  "po_reference": "",
  "quote_id": "",
  "savings": -9007199254740991,
  "sell_total": -9007199254740991,
  "title": "",
  "total_qty": -9007199254740991,
  "valid_until": ""
}
```

##### 400, 401, 403, 404

- `400` \`version\` is not a positive integer (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote or version in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidordersif"></a>

### Download a quote's Order SIF

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/order.sif`
- **Operation ID:** `getQuoteOrderSif`
- **Tags:** quotes

The quote as a classic Configura Order SIF file (`text/plain`), as an attachment. Carries part numbers, options, quantities, list and customer prices; never dealer cost. Ad-hoc charges have no part number and are left out. `?version=n` builds from that presented version; absent, from the presented version if the quote has one, else from the live lines, so the file matches what the customer saw. `POST /v1/quotes/import` reads the file back.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`version`**: `integer`, minimum: `1`, maximum: `9007199254740991`

  A version number from `/v1/quotes/{id}/versions`. Absent: the presented version if there is one, else the live lines.

#### Responses

##### 200 Order SIF

**Headers:**

- **`Content-Disposition`**

  `attachment; filename="…"`

  `string`

**Content type:** `text/plain`

`string`

<a id="scalar-example-40"></a>

**Generated example:**

```json
""
```

##### 400, 401, 403, 404

- `400` \`version\` is not a positive integer (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote or version in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidorderxml"></a>

### Download a quote's OFDA XML order

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/order.xml`
- **Operation ID:** `getQuoteOrderXml`
- **Tags:** quotes

The quote as an OFDA XML purchase order (OFDAOrder 04.04.00, `application/xml`), as an attachment. Carries part numbers, options, quantities, list and customer prices; never dealer cost. Ad-hoc charges have no part number and are left out. `?version=n` builds from that presented version; absent, from the presented version if the quote has one, else from the live lines, so the file matches what the customer saw. `POST /v1/quotes/import` reads the file back.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`version`**: `integer`, minimum: `1`, maximum: `9007199254740991`

  A version number from `/v1/quotes/{id}/versions`. Absent: the presented version if there is one, else the live lines.

#### Responses

##### 200 OFDA XML

**Headers:**

- **`Content-Disposition`**

  `attachment; filename="…"`

  `string`

**Content type:** `application/xml`

`string`

<a id="scalar-example-41"></a>

**Generated example:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root></root>
```

##### 400, 401, 403, 404

- `400` \`version\` is not a positive integer (\`parameter_invalid\`).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote or version in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1quotesidpresent-link"></a>

### Revoke a quote's Present link

- **Method:** `DELETE`
- **Path:** `/v1/quotes/{id}/present-link`
- **Operation ID:** `revokePresentLink`
- **Tags:** present

The URL stops working. Comments stay on the quote. Mint again for a new URL. Emits `quote.share_revoked`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The revoked link

**Content type:** `application/json`

[PresentLink](#scalar-schema-presentlink)

A quote's Present link. One active link per quote; addressed through its quote. Beta.

<a id="scalar-example-42"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "quote_id": "",
  "revoked_at": "2026-10-01T15:04:05.000Z",
  "status": "active",
  "url": ""
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote, or the quote has no active Present link (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidpresent-link"></a>

### Get a quote's Present link

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/present-link`
- **Operation ID:** `getPresentLink`
- **Tags:** present

The active link, or the most recent revoked one when none is active. 404 when the quote was never presented by link.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The Present link

**Content type:** `application/json`

[PresentLink](#scalar-schema-presentlink)

A quote's Present link. One active link per quote; addressed through its quote. Beta.

[Generated example](#scalar-example-42)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote, or the quote has no active Present link (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1quotesidpresent-link"></a>

### Mint a quote's Present link

- **Method:** `POST`
- **Path:** `/v1/quotes/{id}/present-link`
- **Operation ID:** `createPresentLink`
- **Tags:** present

Returns the active link (200) or mints one (201). One active link per quote, so a repeat is safe. On a draft it also snapshots a version, moves the quote to `presented` and emits `quote.presented`; the link always serves that snapshot, never the moving draft.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Responses

##### 200, 201

- `200` The link that was already active
- `201` The new link

**Content type:** `application/json`

[PresentLink](#scalar-schema-presentlink)

A quote's Present link. One active link per quote; addressed through its quote. Beta.

[Generated example](#scalar-example-42)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1quotesidpresent-linksend"></a>

### Email a quote's Present link

- **Method:** `POST`
- **Path:** `/v1/quotes/{id}/present-link/send`
- **Operation ID:** `sendPresentLink`
- **Tags:** present

Sends the active link to up to ten addresses as the signed-in person (their name is on the email and their address is its Reply-To). Needs a person: a workspace API key gets `403 forbidden`; use an OAuth token or a personal key. An address sent this link in the last 60 seconds comes back under `skipped`. Limits: the cost-path limiter (5 calls per 60 seconds per caller) and daily send caps per person and per workspace (`429`). Emits `quote.shared`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`to` (required)**: `array`, minItems: `1`, maxItems: `10`

  One to ten email addresses

  **Items:**

  `string`, minLength: `3`, maxLength: `320`
- **`message`**: `string`, maxLength: `500`

  A short note in the email; no links

<a id="scalar-example-43"></a>

**Generated example:**

```json
{
  "message": "",
  "to": [
    ""
  ]
}
```

#### Responses

##### 200 Who the send reached

**Content type:** `application/json`

[PresentLinkSendResult](#scalar-schema-presentlinksendresult)

Who a send reached. Beta.

<a id="scalar-example-44"></a>

**Generated example:**

```json
{
  "sent": [
    ""
  ],
  "skipped": [
    {
      "email": "",
      "reason": "throttled"
    }
  ]
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote, or the quote has no active Present link (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1quotesidversions"></a>

### List a quote's presented versions

- **Method:** `GET`
- **Path:** `/v1/quotes/{id}/versions`
- **Operation ID:** `listQuoteVersions`
- **Tags:** quotes

Every snapshot the quote was presented as, newest first, with its lines and totals. Cost fields (`buy_unit`, `applied_rule_id`, `totals.buy_total`, `totals.margin`, `totals.margin_percent`, `discount_table_revision_id`) are present only when the caller holds `quote_costs:read`. The same rule applies inside each version.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of versions

**Content type:** `application/json`

[QuoteVersionList](#scalar-schema-quoteversionlist)

<a id="scalar-example-45"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "lines": [
        {
          "applied_rule_id": "",
          "buy_unit": -9007199254740991,
          "catalog_item_id": "",
          "description": "",
          "id": "",
          "kind": "catalog",
          "list_unit": -9007199254740991,
          "options": [
            {
              "code": "",
              "description": "",
              "group": "",
              "price_adder": -9007199254740991
            }
          ],
          "position": -9007199254740991,
          "qty": 1,
          "quote_id": "",
          "sell_unit": -9007199254740991,
          "sku": ""
        }
      ],
      "number": 1,
      "quote_id": "",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      }
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such quote in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1roomsid"></a>

### Get a room

- **Method:** `GET`
- **Path:** `/v1/rooms/{id}`
- **Operation ID:** `getRoom`
- **Tags:** rooms

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The room

**Content type:** `application/json`

[Room](#scalar-schema-room)

A room on a floor. Its furniture is the room's layout (`/v1/rooms/{id}/layout`). Beta.

[Generated example](#scalar-example-17)

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such room in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-patch-v1roomsid"></a>

### Update a room

- **Method:** `PATCH`
- **Path:** `/v1/rooms/{id}`
- **Operation ID:** `updateRoom`
- **Tags:** rooms

Changes the fields you send; the rest keep their values. A move or resize that would leave the room overlapping another room, off the plate or on the building core is refused with `409 conflict`, as is a write that lost a race with another writer (re-read and retry). Resizing re-fits the room's doors and windows onto the new walls.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Optional client-generated key (1-255 printable ASCII characters, a UUID is typical) that makes a retry safe. A repeat with the same key and the same request returns the stored response with `Idempotent-Replayed: true` instead of running again. Keys are scoped to your organization (or your user when you have none) and kept for 24 hours. See docs/api.md → Idempotency-Key.

#### Request body

**Required:** `true`

**Content type:** `application/json`

- **`brief`**: `string`, maxLength: `2000`
- **`depth`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior depth, meters
- **`height`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Wall height, meters
- **`name`**: `string`, minLength: `1`, maxLength: `120`
- **`target_seats`**: `integer`, minimum: `0`, maximum: `9007199254740991`
- **`width`**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior width, meters
- **`x`**: `number`, minimum: `0`

  Left edge, meters
- **`y`**: `number`, minimum: `0`

  Top edge, meters

<a id="scalar-example-46"></a>

**Generated example:**

```json
{
  "brief": "",
  "depth": 1,
  "height": 1,
  "name": "",
  "target_seats": 0,
  "width": 1,
  "x": 0,
  "y": 0
}
```

#### Responses

##### 200 The updated room

**Content type:** `application/json`

[Room](#scalar-schema-room)

A room on a floor. Its furniture is the room's layout (`/v1/rooms/{id}/layout`). Beta.

[Generated example](#scalar-example-17)

##### 400, 401, 403, 404, 409

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such room in your workspace (\`not_found\`).
- `409` Refused by the floor check (\`conflict\`): the room would overlap another room, reach off the plate or stand on the building core. The message names the problem.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1roomsidlayout"></a>

### Get a room's layout

- **Method:** `GET`
- **Path:** `/v1/rooms/{id}/layout`
- **Operation ID:** `getRoomLayout`
- **Tags:** rooms

The room's shell and furniture as a sunny-layout document: the same format the Sunny studio exports, described at <https://sunnysdk.com/docs/layout-interchange/>.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Responses

##### 200 The layout document

**Content type:** `application/json`

[LayoutDocument](#scalar-schema-layoutdocument)

sunny-layout v1 interchange document — see docs/layout-interchange.md. The same schema parseLayoutDocument uses at import time.

<a id="scalar-example-47"></a>

**Generated example:**

```json
{
  "format": "sunny-layout",
  "meta": {
    "exportedAt": "",
    "generator": "",
    "name": "",
    "rationale": ""
  },
  "placements": [
    {
      "catalogId": "",
      "config": {
        "artH": 1,
        "artW": 1,
        "attachAt": "",
        "attachT": 0,
        "attachments": [
          {
            "attachAt": "",
            "mount": "",
            "offset": {
              "x": 1,
              "y": 1,
              "yaw": 1
            },
            "parentId": 1,
            "t": 0
          }
        ],
        "doorsOpen": [
          ""
        ],
        "elevation": 1,
        "finish": "",
        "fringed": true,
        "hidden": true,
        "label": "",
        "locked": true,
        "mountH": 1,
        "on": true,
        "open": true,
        "ordered": true,
        "parentId": 1,
        "pileH": 1,
        "power": 0,
        "propParams": {
          "category": "storage",
          "daylight": 0,
          "depth": 0.005,
          "diagonal": 10,
          "fit": "contain",
          "frame": 0,
          "fringe": true,
          "front": "glass",
          "fullness": 1.3,
          "height": 0.15,
          "length": 0.1,
          "mat": 0,
          "offsetX": -1,
          "offsetY": -1,
          "opening": 0,
          "panelCount": 2,
          "panelLength": 2.1336,
          "portrait": true,
          "preset": "default",
          "ratio": "16:9",
          "shape": "rect",
          "slatAngle": -80,
          "width": 0.15,
          "windowDrop": 0.6,
          "windowTop": 0.6
        },
        "raiseT": 1,
        "raised": true,
        "rotation": 1,
        "scale": 1,
        "selectable": true,
        "size": "",
        "slotFinishes": {
          "shell": ""
        },
        "src": "",
        "suggested": true,
        "system": {
          "familyId": "",
          "presetId": "",
          "presetVersion": 1,
          "rootChildId": 1
        }
      },
      "id": 1,
      "item": {
        "d": 1,
        "name": "",
        "w": 1
      },
      "x": 1,
      "y": 1
    }
  ],
  "room": {
    "architecture": {
      "attachments": [
        {
          "hostIds": [
            ""
          ],
          "placementId": -9007199254740991
        }
      ],
      "components": [
        {
          "hostIds": [
            ""
          ],
          "id": "",
          "interior": true,
          "kind": "floor",
          "normal": [
            1,
            1,
            1
          ],
          "ownerRoomId": "",
          "roomIds": [
            ""
          ],
          "roomNormals": [
            {
              "normal": [
                1,
                1,
                1
              ],
              "roomId": ""
            }
          ]
        }
      ],
      "modelKey": "",
      "origin": [
        1,
        1,
        1
      ],
      "revision": "",
      "roomId": "",
      "sourceId": "",
      "support": {
        "holes": [
          [
            [
              1,
              1
            ],
            [
              1,
              1
            ],
            [
              1,
              1
            ]
          ]
        ],
        "id": "",
        "polygon": [
          [
            1,
            1
          ],
          [
            1,
            1
          ],
          [
            1,
            1
          ]
        ]
      },
      "version": 1
    },
    "d": 1,
    "floorColor": "",
    "floorMaterial": {
      "baseColorKey": "",
      "depthM": 0.02,
      "normalKey": "",
      "normalScale": 0.35,
      "roughness": 0.65,
      "roughnessKey": "",
      "widthM": 0.02
    },
    "floorType": "tile",
    "footprint": {
      "cellSize": 0.1,
      "cells": [
        [
          1,
          1
        ]
      ]
    },
    "h": 1,
    "openings": [
      {
        "center": 1,
        "edge": -9007199254740991,
        "frameColor": "",
        "height": 1,
        "hinge": "start",
        "id": "",
        "kind": "window",
        "leaf": "swing",
        "leafColor": "",
        "leafStyle": "flush",
        "open": true,
        "panes": 0,
        "side": "back",
        "sill": 0,
        "swing": "in",
        "width": 1
      }
    ],
    "w": 1,
    "wallColor": "",
    "wallColors": {
      "additionalProperty": ""
    }
  },
  "version": -9007199254740991
}
```

##### 401, 403, 404

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such room in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-put-v1roomsidlayout"></a>

### Replace a room's layout

- **Method:** `PUT`
- **Path:** `/v1/rooms/{id}/layout`
- **Operation ID:** `replaceRoomLayout`
- **Tags:** rooms

Saves the document as the room's new arrangement, kept as a new version in the room's history. Pieces with a catalog id Sunny doesn't know are left out and listed in `skipped`. A document that resizes the room into another room, off the plate or onto the building core is refused with `409 conflict`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:write`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Request body

**Required:** `true`

**Content type:** `application/json`

[LayoutDocument](#scalar-schema-layoutdocument)

sunny-layout v1 interchange document — see docs/layout-interchange.md. The same schema parseLayoutDocument uses at import time.

<a id="scalar-example-48"></a>

**Generated example:**

```json
{
  "format": "sunny-layout",
  "meta": {
    "exportedAt": "",
    "generator": "",
    "name": "",
    "rationale": ""
  },
  "placements": [
    {
      "catalogId": "",
      "config": {
        "artH": 1,
        "artW": 1,
        "attachAt": "",
        "attachT": 0,
        "attachments": [
          {
            "attachAt": "",
            "mount": "",
            "offset": {
              "x": 1,
              "y": 1,
              "yaw": 1
            },
            "parentId": 1,
            "t": 0
          }
        ],
        "doorsOpen": [
          ""
        ],
        "elevation": 1,
        "finish": "",
        "fringed": true,
        "hidden": true,
        "label": "",
        "locked": true,
        "mountH": 1,
        "on": true,
        "open": true,
        "ordered": true,
        "parentId": 1,
        "pileH": 1,
        "power": 0,
        "propParams": {
          "category": "storage",
          "daylight": 0,
          "depth": 0.005,
          "diagonal": 10,
          "fit": "contain",
          "frame": 0,
          "fringe": true,
          "front": "glass",
          "fullness": 1.3,
          "height": 0.15,
          "length": 0.1,
          "mat": 0,
          "offsetX": -1,
          "offsetY": -1,
          "opening": 0,
          "panelCount": 2,
          "panelLength": 2.1336,
          "portrait": true,
          "preset": "default",
          "ratio": "16:9",
          "shape": "rect",
          "slatAngle": -80,
          "width": 0.15,
          "windowDrop": 0.6,
          "windowTop": 0.6
        },
        "raiseT": 1,
        "raised": true,
        "rotation": 1,
        "scale": 1,
        "selectable": true,
        "size": "",
        "slotFinishes": {
          "shell": ""
        },
        "src": "",
        "suggested": true,
        "system": {
          "familyId": "",
          "presetId": "",
          "presetVersion": 1,
          "rootChildId": 1
        }
      },
      "id": 1,
      "item": {
        "d": 1,
        "name": "",
        "w": 1
      },
      "x": 1,
      "y": 1
    }
  ],
  "room": {
    "architecture": {
      "attachments": [
        {
          "hostIds": [
            ""
          ],
          "placementId": -9007199254740991
        }
      ],
      "components": [
        {
          "hostIds": [
            ""
          ],
          "id": "",
          "interior": true,
          "kind": "floor",
          "normal": [
            1,
            1,
            1
          ],
          "ownerRoomId": "",
          "roomIds": [
            ""
          ],
          "roomNormals": [
            {
              "normal": [
                1,
                1,
                1
              ],
              "roomId": ""
            }
          ]
        }
      ],
      "modelKey": "",
      "origin": [
        1,
        1,
        1
      ],
      "revision": "",
      "roomId": "",
      "sourceId": "",
      "support": {
        "holes": [
          [
            [
              1,
              1
            ],
            [
              1,
              1
            ],
            [
              1,
              1
            ]
          ]
        ],
        "id": "",
        "polygon": [
          [
            1,
            1
          ],
          [
            1,
            1
          ],
          [
            1,
            1
          ]
        ]
      },
      "version": 1
    },
    "d": 1,
    "floorColor": "",
    "floorMaterial": {
      "baseColorKey": "",
      "depthM": 0.02,
      "normalKey": "",
      "normalScale": 0.35,
      "roughness": 0.65,
      "roughnessKey": "",
      "widthM": 0.02
    },
    "floorType": "tile",
    "footprint": {
      "cellSize": 0.1,
      "cells": [
        [
          1,
          1
        ]
      ]
    },
    "h": 1,
    "openings": [
      {
        "center": 1,
        "edge": -9007199254740991,
        "frameColor": "",
        "height": 1,
        "hinge": "start",
        "id": "",
        "kind": "window",
        "leaf": "swing",
        "leafColor": "",
        "leafStyle": "flush",
        "open": true,
        "panes": 0,
        "side": "back",
        "sill": 0,
        "swing": "in",
        "width": 1
      }
    ],
    "w": 1,
    "wallColor": "",
    "wallColors": {
      "additionalProperty": ""
    }
  },
  "version": -9007199254740991
}
```

#### Responses

##### 200 What was saved

**Content type:** `application/json`

[LayoutImportResult](#scalar-schema-layoutimportresult)

What a layout import saved. Beta.

<a id="scalar-example-49"></a>

**Generated example:**

```json
{
  "placed": -9007199254740991,
  "problems": [
    ""
  ],
  "room_id": "",
  "skipped": [
    {
      "catalog_id": "",
      "index": -9007199254740991,
      "message": ""
    }
  ]
}
```

##### 400, 401, 403, 404, 409

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:write\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such room in your workspace (\`not_found\`).
- `409` Refused by the floor check (\`conflict\`): the room would overlap another room, reach off the plate or stand on the building core. The message names the problem.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1roomsidversions"></a>

### List a room's versions

- **Method:** `GET`
- **Path:** `/v1/rooms/{id}/versions`
- **Operation ID:** `listRoomVersions`
- **Tags:** rooms

The room's saved versions, newest first: agent passes and manual saves. Pass `next_cursor` back as `cursor` for the next page.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Path parameters

- **`id` (required)**: `string`

#### Query parameters

- **`limit`**: `integer`, minimum: `1`, maximum: `100`

  Page size, 1-100. Defaults to 25.
- **`cursor`**: `string`, minLength: `1`

  `next_cursor` from the previous page

#### Responses

##### 200 One page of versions

**Content type:** `application/json`

[RoomVersionList](#scalar-schema-roomversionlist)

<a id="scalar-example-50"></a>

**Generated example:**

```json
{
  "data": [
    {
      "brief": "",
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "item_count": 0,
      "name": "",
      "parent_id": "",
      "status": "done"
    }
  ],
  "next_cursor": ""
}
```

##### 400, 401, 403, 404

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).
- `404` No such room in your workspace (\`not_found\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1sandboxreset"></a>

### Reset the sandbox

- **Method:** `POST`
- **Path:** `/v1/sandbox/reset`
- **Operation ID:** `resetSandbox`
- **Tags:** sandbox

Deletes every quote, customer, order and discount table in the caller's sandbox organization and restores the fixture set: the default fixture discount table and the fixture customer. API keys and webhook endpoints are kept. Writes an audit event (`sandbox.reset`).

Only a sandbox test key (`sunny_wsk_test_…`) carrying `org:admin` may call this. Calling it with a live organization's key is refused (`sandbox_requires_test_key` / `test_key_requires_sandbox` for a mismatched key, `sandbox_only` otherwise).

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `org:admin`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Responses

##### 200 The sandbox was reset

**Content type:** `application/json`

The result of a sandbox reset. Beta.

- **`org_id` (required)**: `string`

  The sandbox organization that was reset
- **`removed` (required)**: `object`

  Rows the reset removed before re-seeding the fixtures
  - **`customers` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

    Customers deleted
  - **`discount_tables` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

    Discount tables deleted
  - **`orders` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

    Orders deleted
  - **`quotes` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

    Quotes deleted, with their lines
- **`reset_at` (required)**: `string`

  When the reset finished (ISO 8601)

<a id="scalar-example-51"></a>

**Generated example:**

```json
{
  "org_id": "",
  "removed": {
    "customers": 0,
    "discount_tables": 0,
    "orders": 0,
    "quotes": 0
  },
  "reset_at": ""
}
```

##### 401, 403

- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`org:admin\` scope (\`insufficient_scope\`); a live organization (\`sandbox_only\`); a test key on a live organization (\`test_key_requires_sandbox\`) or a live key on a sandbox (\`sandbox_requires_test_key\`); or not a workspace key (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1search"></a>

### Search

- **Method:** `GET`
- **Path:** `/v1/search`
- **Operation ID:** `getSearchResults`
- **Tags:** search

Projects, rooms, typicals, families, catalog items, customers and quotes matching `q`, best first, a few of each. `include` names the sections to return. Each section needs its own scope (`projects:read` for projects and rooms, `catalog:read` for the catalog, `quotes:read` for customers and quotes); a section your scopes don't cover is empty. Read a result in full through its own resource, e.g. `GET /v1/rooms/{id}`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `projects:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `catalog:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **oauth2**: OAuth 2.0: authorization code, authorize `https://auth.sunnysdk.com/api/auth/oauth2/authorize`, token `https://auth.sunnysdk.com/api/auth/oauth2/token`, refresh `https://auth.sunnysdk.com/api/auth/oauth2/token`, scopes: `quotes:read`

  OAuth 2.1 authorization code + PKCE. A valid Bearer token with the operation's scope is sufficient on its own. Discovery: <https://auth.sunnysdk.com/.well-known/oauth-authorization-server>

Or:

- **apiKeyAuth**: API key in header `x-api-key`

  API key (`sunny_sk_…` personal, minted under Account → API keys; `sunny_wsk_…` workspace, minted under Organization → API keys). Personal keys carry the non-elevated action scopes; workspace keys may also carry embeds:\* and webhooks:manage.

#### Query parameters

- **`q` (required)**: `string`, minLength: `1`, maxLength: `200`

  The text to find
- **`include`**: `string`

  Comma-separated sections to return: `projects`, `rooms`, `typicals`, `families`, `items`, `customers`, `quotes`. All by default.

#### Responses

##### 200 Matches in each section

**Content type:** `application/json`

[SearchResult](#scalar-schema-searchresult)

Matches in each section. A section your scopes don't cover, or that `include` leaves out, is an empty list. Beta.

<a id="scalar-example-52"></a>

**Generated example:**

```json
{
  "customers": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "email": "",
      "id": "",
      "name": "",
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "families": [
    {
      "items": [
        {
          "agent_note": "",
          "category": "table",
          "description": "",
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "family": "",
          "finishes": [
            {
              "color": "#8a6a4f",
              "material": "",
              "name": "",
              "price_adder": {
                "amount": -9007199254740991,
                "currency": "USD"
              }
            }
          ],
          "id": "",
          "image_url": "",
          "internal_note": "",
          "list_price": {
            "amount": -9007199254740991,
            "currency": "USD"
          },
          "manufacturer": "",
          "model_number": "",
          "model_takes_finish_color": true,
          "model_url": "",
          "name": "",
          "placement": {
            "color": "",
            "flags": [
              ""
            ],
            "placeholder": true,
            "prop": {
              "defaults": {
                "additionalProperty": null
              },
              "fields": [
                ""
              ],
              "kind": "",
              "schema": {
                "additionalProperty": null
              }
            },
            "seats": -9007199254740991,
            "shape": "rect"
          },
          "plan_symbol": "manufacturer",
          "reference_photos": [
            {
              "license": "",
              "scope": "exact",
              "source": "",
              "url": ""
            }
          ],
          "retired": true,
          "seat_type": "task",
          "sizes": [
            {
              "dimensions": {
                "depth": 1,
                "height": 1,
                "width": 1
              },
              "name": "",
              "price_adder": {
                "amount": -9007199254740991,
                "currency": "USD"
              }
            }
          ],
          "sku": ""
        }
      ],
      "key": "",
      "manufacturer": "",
      "name": ""
    }
  ],
  "items": [
    {
      "agent_note": "",
      "category": "table",
      "description": "",
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "family": "",
      "finishes": [
        {
          "color": "#8a6a4f",
          "material": "",
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "id": "",
      "image_url": "",
      "internal_note": "",
      "list_price": {
        "amount": -9007199254740991,
        "currency": "USD"
      },
      "manufacturer": "",
      "model_number": "",
      "model_takes_finish_color": true,
      "model_url": "",
      "name": "",
      "placement": {
        "color": "",
        "flags": [
          ""
        ],
        "placeholder": true,
        "prop": {
          "defaults": {
            "additionalProperty": null
          },
          "fields": [
            ""
          ],
          "kind": "",
          "schema": {
            "additionalProperty": null
          }
        },
        "seats": -9007199254740991,
        "shape": "rect"
      },
      "plan_symbol": "manufacturer",
      "reference_photos": [
        {
          "license": "",
          "scope": "exact",
          "source": "",
          "url": ""
        }
      ],
      "retired": true,
      "seat_type": "task",
      "sizes": [
        {
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "sku": ""
    }
  ],
  "projects": [
    {
      "id": "",
      "name": ""
    }
  ],
  "quotes": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "currency": "USD",
      "customer_id": "",
      "discount_table_revision_id": "",
      "id": "",
      "name": "",
      "number": "Q-000123",
      "status": "draft",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      },
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "rooms": [
    {
      "depth": 1,
      "floor_id": "",
      "floor_name": "",
      "id": "",
      "name": "",
      "project_id": "",
      "project_name": "",
      "width": 1
    }
  ],
  "typicals": [
    {
      "family": "",
      "id": "",
      "image_url": "",
      "manufacturer": "",
      "name": "",
      "parts": [
        {
          "count": -9007199254740991,
          "item": {
            "agent_note": "",
            "category": "table",
            "description": "",
            "dimensions": {
              "depth": 1,
              "height": 1,
              "width": 1
            },
            "family": "",
            "finishes": [
              {
                "color": "#8a6a4f",
                "material": "",
                "name": "",
                "price_adder": {
                  "amount": -9007199254740991,
                  "currency": "USD"
                }
              }
            ],
            "id": "",
            "image_url": "",
            "internal_note": "",
            "list_price": {
              "amount": -9007199254740991,
              "currency": "USD"
            },
            "manufacturer": "",
            "model_number": "",
            "model_takes_finish_color": true,
            "model_url": "",
            "name": "",
            "placement": {
              "color": "",
              "flags": [
                ""
              ],
              "placeholder": true,
              "prop": {
                "defaults": {
                  "additionalProperty": null
                },
                "fields": [
                  ""
                ],
                "kind": "",
                "schema": {
                  "additionalProperty": null
                }
              },
              "seats": -9007199254740991,
              "shape": "rect"
            },
            "plan_symbol": "manufacturer",
            "reference_photos": [
              {
                "license": "",
                "scope": "exact",
                "source": "",
                "url": ""
              }
            ],
            "retired": true,
            "seat_type": "task",
            "sizes": [
              {
                "dimensions": {
                  "depth": 1,
                  "height": 1,
                  "width": 1
                },
                "name": "",
                "price_adder": {
                  "amount": -9007199254740991,
                  "currency": "USD"
                }
              }
            ],
            "sku": ""
          }
        }
      ],
      "tags": [
        ""
      ]
    }
  ]
}
```

##### 400, 401, 403

- `400` A request field is invalid (\`parameter_invalid\`, \`param\` names it).
- `401` No credentials (\`credentials_missing\`), or a malformed, expired, or revoked Bearer token / API key (\`invalid_token\`, \`invalid_api_key\`).
- `403` Valid credentials without the \`projects:read\` or \`catalog:read\` or \`quotes:read\` scope (\`insufficient_scope\`), or not allowed for this caller (\`forbidden\`).

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Rate limited (\`rate_limited\`); retry after \`Retry-After\` seconds.

**Headers:**

- **`Retry-After`**

  Seconds to wait

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

## Schemas

<a id="scalar-schema-auditevent"></a>

### AuditEvent

**Type:** `object`

- **`action` (required)**: `string`

  Dotted `<target>.<verb>`
- **`actor` (required)**: `object`
  - **`id` (required)**: `string`

    User id (`user`), API key id (`api_key`), OAuth client id (`oauth_client`), or a job name (`system`)
  - **`kind` (required)**: `string`, possible values: `"user", "api_key", "oauth_client", "system"`

    New kinds may be added; handle values you don't recognise.
  - **`user_id`**: `string`

    The person behind an OAuth client or personal API key; omitted otherwise
- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`org_id` (required)**: `string`

  The workspace the event belongs to
- **`summary` (required)**: `string`
- **`target` (required)**: `object`
  - **`type` (required)**: `string`
  - **`id`**: `string`
- **`detail`**: `object`

  Action-specific detail. Free-form; keys vary by action.

  **Additional properties:**

  `any`
- **`request_id`**: `string`

  `X-Request-Id` of the request that wrote the event

<a id="scalar-example-53"></a>

**Generated example:**

```json
{
  "action": "quote.updated",
  "actor": {
    "id": "",
    "kind": "user",
    "user_id": ""
  },
  "created_at": "2026-10-01T15:04:05.000Z",
  "detail": {
    "additionalProperty": null
  },
  "id": "",
  "org_id": "",
  "request_id": "",
  "summary": "",
  "target": {
    "id": "",
    "type": "quote"
  }
}
```

<a id="scalar-schema-auditeventlist"></a>

### AuditEventList

**Type:** `object`

- **`data` (required)**: array of [AuditEvent](#scalar-schema-auditevent)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-54"></a>

**Generated example:**

```json
{
  "data": [
    {
      "action": "quote.updated",
      "actor": {
        "id": "",
        "kind": "user",
        "user_id": ""
      },
      "created_at": "2026-10-01T15:04:05.000Z",
      "detail": {
        "additionalProperty": null
      },
      "id": "",
      "org_id": "",
      "request_id": "",
      "summary": "",
      "target": {
        "id": "",
        "type": "quote"
      }
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-catalogfinish"></a>

### CatalogFinish

**Type:** `object`

One finish a catalog item comes in. Beta.

- **`color` (required)**: `string`

  Swatch color as `#rrggbb`
- **`name` (required)**: `string`
- **`material`**: `string`

  Id of the material Sunny's 3D viewer applies for this finish, when it has one
- **`price_adder`**: [Money](#scalar-schema-money)

  Added to `list_price` when this finish is chosen; may be negative

<a id="scalar-example-55"></a>

**Generated example:**

```json
{
  "color": "#8a6a4f",
  "material": "",
  "name": "",
  "price_adder": {
    "amount": -9007199254740991,
    "currency": "USD"
  }
}
```

<a id="scalar-schema-catalogitem"></a>

### CatalogItem

**Type:** `object`

A catalog product. Optional sections come with `include`; notes depend on your scopes.

- **`category` (required)**: `string`, possible values: `"table", "seating", "storage", "accent", "desk", "lighting"`

  New values may be added; handle values you don't recognise.
- **`dimensions` (required)**: [Dimensions](#scalar-schema-dimensions)

  Base configuration size. In meters, whatever unit the caller displays; convert for display (1 m = 39.37 in). Beta.
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`agent_note`**: `string`

  Curator guidance for an AI agent placing or quoting the item. Present only when the caller holds `docs:read`. Beta.
- **`description`**: `string`

  The manufacturer's product description. Beta.
- **`family`**: `string`

  Product family, series or system
- **`finishes`**: array of [CatalogFinish](#scalar-schema-catalogfinish)

  With `include=options`: the finishes it comes in, `[]` when none. Beta.
- **`image_url`**: `string`

  A product image (the poster render). Beta.
- **`internal_note`**: `string`

  Curator notes for staff. Present only for a catalog curator (a site admin or a caller holding `catalog:write`). Beta.
- **`list_price`**: [Money](#scalar-schema-money)

  List price of the base configuration; omitted when the item is unpriced
- **`manufacturer`**: `string`
- **`model_number`**: `string`

  The manufacturer's model number, when it differs from the SKU. Beta.
- **`model_takes_finish_color`**: `boolean`

  With `include=media`: whether the model is tinted with the chosen finish's `color`. When false, its own materials stay as authored. Beta.
- **`model_url`**: `string`

  With `include=media`: a glTF binary (`.glb`) 3D model, when there is one. Beta.
- **`placement`**: [CatalogPlacement](#scalar-schema-catalogplacement)

  With `include=placement`. Beta.
- **`plan_symbol`**: `string`, possible values: `"manufacturer", "generated"`

  Present when Sunny draws the item in plans with its own symbol: `manufacturer` for the maker's drawing, `generated` for one drawn from its 3D model and approved by Sunny. Omitted when plans draw a generic shape. Beta.
- **`reference_photos`**: array of [CatalogPhoto](#scalar-schema-catalogphoto)

  With `include=media`: real product photos, `[]` when none. Beta.
- **`retired`**: `boolean`, const: `true`

  Present when the item is no longer offered. It still resolves by id, so a quote line naming it can be looked up, but lists never include it. Beta.
- **`seat_type`**: `string`, possible values: `"task", "conference", "guest", "stool", "lounge", "sofa", "bench", "ottoman", "booth"`

  Seating only: what kind of seat it is, read from the product's name and family. `task`, `conference` and `guest` chairs pull up to a desk or table; the rest stand on their own. New values may be added; handle values you don't recognise. Beta.
- **`sizes`**: array of [CatalogSize](#scalar-schema-catalogsize)

  With `include=options`: the sizes it comes in, `[]` when none. Beta.
- **`sku`**: `string`

  Manufacturer SKU, when known

<a id="scalar-example-56"></a>

**Generated example:**

```json
{
  "agent_note": "",
  "category": "table",
  "description": "",
  "dimensions": {
    "depth": 1,
    "height": 1,
    "width": 1
  },
  "family": "",
  "finishes": [
    {
      "color": "#8a6a4f",
      "material": "",
      "name": "",
      "price_adder": {
        "amount": -9007199254740991,
        "currency": "USD"
      }
    }
  ],
  "id": "",
  "image_url": "",
  "internal_note": "",
  "list_price": {
    "amount": -9007199254740991,
    "currency": "USD"
  },
  "manufacturer": "",
  "model_number": "",
  "model_takes_finish_color": true,
  "model_url": "",
  "name": "",
  "placement": {
    "color": "",
    "flags": [
      ""
    ],
    "placeholder": true,
    "prop": {
      "defaults": {
        "additionalProperty": null
      },
      "fields": [
        ""
      ],
      "kind": "",
      "schema": {
        "additionalProperty": null
      }
    },
    "seats": -9007199254740991,
    "shape": "rect"
  },
  "plan_symbol": "manufacturer",
  "reference_photos": [
    {
      "license": "",
      "scope": "exact",
      "source": "",
      "url": ""
    }
  ],
  "retired": true,
  "seat_type": "task",
  "sizes": [
    {
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "name": "",
      "price_adder": {
        "amount": -9007199254740991,
        "currency": "USD"
      }
    }
  ],
  "sku": ""
}
```

<a id="scalar-schema-catalogitemlist"></a>

### CatalogItemList

**Type:** `object`

- **`data` (required)**: array of [CatalogItem](#scalar-schema-catalogitem)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-57"></a>

**Generated example:**

```json
{
  "data": [
    {
      "agent_note": "",
      "category": "table",
      "description": "",
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "family": "",
      "finishes": [
        {
          "color": "#8a6a4f",
          "material": "",
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "id": "",
      "image_url": "",
      "internal_note": "",
      "list_price": {
        "amount": -9007199254740991,
        "currency": "USD"
      },
      "manufacturer": "",
      "model_number": "",
      "model_takes_finish_color": true,
      "model_url": "",
      "name": "",
      "placement": {
        "color": "",
        "flags": [
          ""
        ],
        "placeholder": true,
        "prop": {
          "defaults": {
            "additionalProperty": null
          },
          "fields": [
            ""
          ],
          "kind": "",
          "schema": {
            "additionalProperty": null
          }
        },
        "seats": -9007199254740991,
        "shape": "rect"
      },
      "plan_symbol": "manufacturer",
      "reference_photos": [
        {
          "license": "",
          "scope": "exact",
          "source": "",
          "url": ""
        }
      ],
      "retired": true,
      "seat_type": "task",
      "sizes": [
        {
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "sku": ""
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-catalogphoto"></a>

### CatalogPhoto

**Type:** `object`

A real product photo. Beta.

- **`url` (required)**: `string`
- **`license`**: `string`

  The licence the photo is used under
- **`scope`**: `string`, possible values: `"exact", "family"`

  `exact`: this product. `family`: a sibling in its family, close but not identical.
- **`source`**: `string`

  Where the photo came from

<a id="scalar-example-58"></a>

**Generated example:**

```json
{
  "license": "",
  "scope": "exact",
  "source": "",
  "url": ""
}
```

<a id="scalar-schema-catalogplacement"></a>

### CatalogPlacement

**Type:** `object`

What Sunny's layout tools need to place the item. Beta.

- **`color` (required)**: `string`

  Plan-view fill color as `#rrggbb`
- **`shape` (required)**: `string`, possible values: `"rect", "round"`

  Footprint outline. New values may be added; handle values you don't recognise.
- **`flags`**: `array of string`

  Placement behaviours Sunny's layout tools support for this item, such as `wallSnap/mountH` or `ceilingMount`. The set grows; ignore flags you don't recognise.
- **`placeholder`**: `boolean`, const: `true`

  A generic stand-in rather than a real product
- **`prop`**: `object`

  Parameters of a parametric item such as a rug
  - **`defaults` (required)**: `object`

    **Additional properties:**

    `any`
  - **`fields` (required)**: `array of string`
  - **`kind` (required)**: `string`
  - **`schema` (required)**: `object`

    JSON Schema for the parameters this prop accepts

    **Additional properties:**

    `any`
- **`seats`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  People it seats, when it seats any

<a id="scalar-example-59"></a>

**Generated example:**

```json
{
  "color": "",
  "flags": [
    ""
  ],
  "placeholder": true,
  "prop": {
    "defaults": {
      "additionalProperty": null
    },
    "fields": [
      ""
    ],
    "kind": "",
    "schema": {
      "additionalProperty": null
    }
  },
  "seats": -9007199254740991,
  "shape": "rect"
}
```

<a id="scalar-schema-catalogsize"></a>

### CatalogSize

**Type:** `object`

One size a catalog item comes in. Beta.

- **`dimensions` (required)**: [Dimensions](#scalar-schema-dimensions)

  Physical size. In meters, whatever unit the caller displays; convert for display (1 m = 39.37 in).
- **`name` (required)**: `string`
- **`price_adder`**: [Money](#scalar-schema-money)

  Added to `list_price` when this size is chosen; may be negative

<a id="scalar-example-60"></a>

**Generated example:**

```json
{
  "dimensions": {
    "depth": 1,
    "height": 1,
    "width": 1
  },
  "name": "",
  "price_adder": {
    "amount": -9007199254740991,
    "currency": "USD"
  }
}
```

<a id="scalar-schema-customer"></a>

### Customer

**Type:** `object`

A customer a workspace quotes for.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`updated_at` (required)**: `string`

  ISO 8601, UTC
- **`email`**: `string`

<a id="scalar-example-61"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "email": "",
  "id": "",
  "name": "",
  "updated_at": "2026-10-01T15:04:05.000Z"
}
```

<a id="scalar-schema-customerlist"></a>

### CustomerList

**Type:** `object`

- **`data` (required)**: array of [Customer](#scalar-schema-customer)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-62"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "email": "",
      "id": "",
      "name": "",
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-deleted"></a>

### Deleted

**Type:** `object`

Confirms a delete. Beta.

- **`deleted` (required)**: `boolean`, const: `true`
- **`id` (required)**: `string`

  The deleted object's id

<a id="scalar-example-63"></a>

**Generated example:**

```json
{
  "deleted": true,
  "id": ""
}
```

<a id="scalar-schema-dimensions"></a>

### Dimensions

**Type:** `object`

Physical size. In meters, whatever unit the caller displays; convert for display (1 m = 39.37 in).

- **`depth` (required)**: `number`

  Front to back, as placed
- **`width` (required)**: `number`

  Side to side, as placed
- **`height`**: `number`

  Floor to top, when known

<a id="scalar-example-64"></a>

**Generated example:**

```json
{
  "depth": 1,
  "height": 1,
  "width": 1
}
```

<a id="scalar-schema-discountrule"></a>

### DiscountRule

**Type:** `object`

One discount rule. Beta.

- **`buy_percents` (required)**: `array of number`

  Left-to-right discount chain off list, e.g. `[50, 10, 10]`
- **`id` (required)**: `string`

  Opaque id (C1)
- **`match_type` (required)**: `string`, possible values: `"manufacturer", "catalog_code", "group_code", "sku"`

  New values may be added; handle values you don't recognise.
- **`match_value` (required)**: `string`
- **`priority` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Lower wins among rules that match equally specifically
- **`sell_method`**: `string`, possible values: `"markup_percent", "margin_percent", "sell_percent"`

  How sell is derived from buy or list; omitted when the rule sets none
- **`sell_value`**: `number`

  The percent `sell_method` applies; omitted with it

<a id="scalar-example-65"></a>

**Generated example:**

```json
{
  "buy_percents": [
    1
  ],
  "id": "",
  "match_type": "manufacturer",
  "match_value": "",
  "priority": -9007199254740991,
  "sell_method": "markup_percent",
  "sell_value": 1
}
```

<a id="scalar-schema-discounttable"></a>

### DiscountTable

**Type:** `object`

A workspace's dealer discount table: dealer cost, so it needs `quote_costs:read`. Beta.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`is_default` (required)**: `boolean`

  Whether new quotes bind this table's latest revision
- **`name` (required)**: `string`
- **`revisions` (required)**: array of [DiscountTableRevision](#scalar-schema-discounttablerevision)

<a id="scalar-example-66"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "id": "",
  "is_default": true,
  "name": "",
  "revisions": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "effective_from": "2026-10-01T15:04:05.000Z",
      "effective_to": "2026-10-01T15:04:05.000Z",
      "id": "",
      "label": "",
      "rules": [
        {
          "buy_percents": [
            1
          ],
          "id": "",
          "match_type": "manufacturer",
          "match_value": "",
          "priority": -9007199254740991,
          "sell_method": "markup_percent",
          "sell_value": 1
        }
      ]
    }
  ]
}
```

<a id="scalar-schema-discounttablelist"></a>

### DiscountTableList

**Type:** `object`

- **`data` (required)**: array of [DiscountTable](#scalar-schema-discounttable)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-67"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "is_default": true,
      "name": "",
      "revisions": [
        {
          "created_at": "2026-10-01T15:04:05.000Z",
          "effective_from": "2026-10-01T15:04:05.000Z",
          "effective_to": "2026-10-01T15:04:05.000Z",
          "id": "",
          "label": "",
          "rules": [
            {
              "buy_percents": [
                1
              ],
              "id": "",
              "match_type": "manufacturer",
              "match_value": "",
              "priority": -9007199254740991,
              "sell_method": "markup_percent",
              "sell_value": 1
            }
          ]
        }
      ]
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-discounttablerevision"></a>

### DiscountTableRevision

**Type:** `object`

One dated revision of a discount table. Beta.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`label` (required)**: `string`
- **`rules` (required)**: array of [DiscountRule](#scalar-schema-discountrule)
- **`effective_from`**: `string`

  ISO 8601, UTC
- **`effective_to`**: `string`

  ISO 8601, UTC

<a id="scalar-example-68"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "effective_from": "2026-10-01T15:04:05.000Z",
  "effective_to": "2026-10-01T15:04:05.000Z",
  "id": "",
  "label": "",
  "rules": [
    {
      "buy_percents": [
        1
      ],
      "id": "",
      "match_type": "manufacturer",
      "match_value": "",
      "priority": -9007199254740991,
      "sell_method": "markup_percent",
      "sell_value": 1
    }
  ]
}
```

<a id="scalar-schema-error"></a>

### Error

**Type:** `object`

- **`error` (required)**: `object`
  - **`code` (required)**: `string`

    Machine-readable error code, e.g. `parameter_invalid`, `insufficient_scope`, `rate_limited`. Additive: the set grows, and a code is never renamed or repurposed. Handle a code you don't recognise. `x-sunny-error-codes` lists the current set.
  - **`message` (required)**: `string`

    Human-readable explanation. May change; don't parse it.
  - **`request_id` (required)**: `string`

    Same value as the `X-Request-Id` response header
  - **`type` (required)**: `string`, possible values: `"invalid_request_error", "authentication_error", "permission_error", "idempotency_error", "rate_limit_error", "api_error"`

    Broad error class. The documented values are the current set and may grow; handle a `type` you don't recognise, the same as an unknown `code`. Switch on `code` for specifics.
  - **`param`**: `string`

    The request field (or header) at fault, when there is one

<a id="scalar-example-69"></a>

**Generated example:**

```json
{
  "error": {
    "code": "parameter_invalid",
    "message": "",
    "param": "limit",
    "request_id": "",
    "type": "invalid_request_error"
  }
}
```

<a id="scalar-schema-floor"></a>

### Floor

**Type:** `object`

One storey of a project. Beta.

- **`budget` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

  The floor's furniture budget, in whole units of the workspace currency
- **`depth` (required)**: `number`

  Floor plate depth (y), meters
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`project_id` (required)**: `string`

  The project the floor belongs to
- **`room_ids` (required)**: `array of string`

  The rooms on this floor
- **`structure` (required)**: [FloorStructure](#scalar-schema-floorstructure)

  The fixed parts of a floor plate the rooms are planned around. Beta.
- **`target_headcount` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

  How many people the floor should seat
- **`width` (required)**: `number`

  Floor plate width (x), meters
- **`floor_color`**: `string`

  A tint on the default floor finish, as #rrggbb
- **`floor_rotation`**

  Which way the floorboards run: 90 turns them a quarter; absent = 0

  **Any of:**
  - `number`, const: `0`
  - `number`, const: `90`
- **`floor_type`**: `string`, possible values: `"tile", "concrete", "oak", "birch", "walnut", "espresso", "plush", "oatmeal", "sage", "clay", "charcoal"`

  The default floor finish for rooms that don't set their own; absent = tile
- **`page_color`**: `string`

  The background the whole-floor view paints behind the plate, as #rrggbb
- **`wall_color`**: `string`

  The default wall paint for rooms that don't set their own, as #rrggbb

<a id="scalar-example-70"></a>

**Generated example:**

```json
{
  "budget": 0,
  "depth": 1,
  "floor_color": "",
  "floor_rotation": 0,
  "floor_type": "tile",
  "id": "",
  "name": "",
  "page_color": "",
  "project_id": "",
  "room_ids": [
    ""
  ],
  "structure": {
    "circulation": [
      {
        "depth": 1,
        "width": 1,
        "x": 1,
        "y": 1
      }
    ],
    "core": {
      "depth": 1,
      "width": 1,
      "x": 1,
      "y": 1
    },
    "entry": {
      "position": 1,
      "side": "n"
    },
    "facade": [
      "n"
    ]
  },
  "target_headcount": 0,
  "wall_color": "",
  "width": 1
}
```

<a id="scalar-schema-floorcheck"></a>

### FloorCheck

**Type:** `object`

How the rooms on a floor fit the plate and each other. Beta.

- **`notes` (required)**: array of [FloorIssue](#scalar-schema-floorissue)

  Judgement calls worth a look, which can stay
- **`problems` (required)**: array of [FloorIssue](#scalar-schema-floorissue)

  Real faults to fix: rooms overlapping each other, off the plate, or on the building core
- **`status` (required)**: `string`, possible values: `"ok", "problems"`

  `problems` when any problem remains
- **`summary` (required)**: `string`

  One line on the result

<a id="scalar-example-71"></a>

**Generated example:**

```json
{
  "notes": [
    {
      "fix": "",
      "message": "",
      "room_ids": [
        ""
      ],
      "rule": ""
    }
  ],
  "problems": [
    {
      "fix": "",
      "message": "",
      "room_ids": [
        ""
      ],
      "rule": ""
    }
  ],
  "status": "ok",
  "summary": ""
}
```

<a id="scalar-schema-floorissue"></a>

### FloorIssue

**Type:** `object`

- **`message` (required)**: `string`
- **`room_ids` (required)**: `array of string`

  The rooms involved
- **`rule` (required)**: `string`

  Which check found it, e.g. `room-overlap`
- **`fix`**: `string`

  A change that resolves it, when there is one

<a id="scalar-example-72"></a>

**Generated example:**

```json
{
  "fix": "",
  "message": "",
  "room_ids": [
    ""
  ],
  "rule": ""
}
```

<a id="scalar-schema-floorlist"></a>

### FloorList

**Type:** `object`

- **`data` (required)**: array of [Floor](#scalar-schema-floor)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-73"></a>

**Generated example:**

```json
{
  "data": [
    {
      "budget": 0,
      "depth": 1,
      "floor_color": "",
      "floor_rotation": 0,
      "floor_type": "tile",
      "id": "",
      "name": "",
      "page_color": "",
      "project_id": "",
      "room_ids": [
        ""
      ],
      "structure": {
        "circulation": [
          {
            "depth": 1,
            "width": 1,
            "x": 1,
            "y": 1
          }
        ],
        "core": {
          "depth": 1,
          "width": 1,
          "x": 1,
          "y": 1
        },
        "entry": {
          "position": 1,
          "side": "n"
        },
        "facade": [
          "n"
        ]
      },
      "target_headcount": 0,
      "wall_color": "",
      "width": 1
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-floorstructure"></a>

### FloorStructure

**Type:** `object`

The fixed parts of a floor plate the rooms are planned around. Beta.

- **`circulation` (required)**: array of [Rect](#scalar-schema-rect)

  Corridors and other floor area kept clear of rooms
- **`core` (required)**: [Rect](#scalar-schema-rect)

  The building core (stairs, lifts, risers); zero size when the floor has none
- **`entry` (required)**: `object`

  Where people come onto the floor
  - **`position` (required)**: `number`

    Where along that edge, 0-1
  - **`side` (required)**: `string`, possible values: `"n", "e", "s", "w"`

    A plate edge: n (top), e (right), s (bottom), w (left)
- **`facade` (required)**: `array`

  The plate edges with windows to the outside

  **Items:**

  `string`, possible values: `"n", "e", "s", "w"`

  A plate edge: n (top), e (right), s (bottom), w (left)

<a id="scalar-example-74"></a>

**Generated example:**

```json
{
  "circulation": [
    {
      "depth": 1,
      "width": 1,
      "x": 1,
      "y": 1
    }
  ],
  "core": {
    "depth": 1,
    "width": 1,
    "x": 1,
    "y": 1
  },
  "entry": {
    "position": 1,
    "side": "n"
  },
  "facade": [
    "n"
  ]
}
```

<a id="scalar-schema-layoutdocument"></a>

### LayoutDocument

**Type:** `object`

sunny-layout v1 interchange document — see docs/layout-interchange.md. The same schema parseLayoutDocument uses at import time.

- **`format` (required)**: `string`, const: `"sunny-layout"`
- **`placements` (required)**: array of [LayoutPlacement](#scalar-schema-layoutplacement)
- **`room` (required)**: [LayoutRoom](#scalar-schema-layoutroom)

  Room shell in a sunny-layout document. Openings are always parametric; exportLayout materializes legacy windows/door/doorPos before write.
- **`version` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Currently only 1 is supported
- **`meta`**: `object`
  - **`exportedAt`**: `string`
  - **`generator`**: `string`
  - **`name`**: `string`
  - **`rationale`**: `string`

<a id="scalar-example-75"></a>

**Generated example:**

```json
{
  "format": "sunny-layout",
  "meta": {
    "exportedAt": "",
    "generator": "",
    "name": "",
    "rationale": ""
  },
  "placements": [
    {
      "catalogId": "",
      "config": {
        "artH": 1,
        "artW": 1,
        "attachAt": "",
        "attachT": 0,
        "attachments": [
          {
            "attachAt": "",
            "mount": "",
            "offset": {
              "x": 1,
              "y": 1,
              "yaw": 1
            },
            "parentId": 1,
            "t": 0
          }
        ],
        "doorsOpen": [
          ""
        ],
        "elevation": 1,
        "finish": "",
        "fringed": true,
        "hidden": true,
        "label": "",
        "locked": true,
        "mountH": 1,
        "on": true,
        "open": true,
        "ordered": true,
        "parentId": 1,
        "pileH": 1,
        "power": 0,
        "propParams": {
          "category": "storage",
          "daylight": 0,
          "depth": 0.005,
          "diagonal": 10,
          "fit": "contain",
          "frame": 0,
          "fringe": true,
          "front": "glass",
          "fullness": 1.3,
          "height": 0.15,
          "length": 0.1,
          "mat": 0,
          "offsetX": -1,
          "offsetY": -1,
          "opening": 0,
          "panelCount": 2,
          "panelLength": 2.1336,
          "portrait": true,
          "preset": "default",
          "ratio": "16:9",
          "shape": "rect",
          "slatAngle": -80,
          "width": 0.15,
          "windowDrop": 0.6,
          "windowTop": 0.6
        },
        "raiseT": 1,
        "raised": true,
        "rotation": 1,
        "scale": 1,
        "selectable": true,
        "size": "",
        "slotFinishes": {
          "shell": ""
        },
        "src": "",
        "suggested": true,
        "system": {
          "familyId": "",
          "presetId": "",
          "presetVersion": 1,
          "rootChildId": 1
        }
      },
      "id": 1,
      "item": {
        "d": 1,
        "name": "",
        "w": 1
      },
      "x": 1,
      "y": 1
    }
  ],
  "room": {
    "architecture": {
      "attachments": [
        {
          "hostIds": [
            ""
          ],
          "placementId": -9007199254740991
        }
      ],
      "components": [
        {
          "hostIds": [
            ""
          ],
          "id": "",
          "interior": true,
          "kind": "floor",
          "normal": [
            1,
            1,
            1
          ],
          "ownerRoomId": "",
          "roomIds": [
            ""
          ],
          "roomNormals": [
            {
              "normal": [
                1,
                1,
                1
              ],
              "roomId": ""
            }
          ]
        }
      ],
      "modelKey": "",
      "origin": [
        1,
        1,
        1
      ],
      "revision": "",
      "roomId": "",
      "sourceId": "",
      "support": {
        "holes": [
          [
            [
              1,
              1
            ],
            [
              1,
              1
            ],
            [
              1,
              1
            ]
          ]
        ],
        "id": "",
        "polygon": [
          [
            1,
            1
          ],
          [
            1,
            1
          ],
          [
            1,
            1
          ]
        ]
      },
      "version": 1
    },
    "d": 1,
    "floorColor": "",
    "floorMaterial": {
      "baseColorKey": "",
      "depthM": 0.02,
      "normalKey": "",
      "normalScale": 0.35,
      "roughness": 0.65,
      "roughnessKey": "",
      "widthM": 0.02
    },
    "floorType": "tile",
    "footprint": {
      "cellSize": 0.1,
      "cells": [
        [
          1,
          1
        ]
      ]
    },
    "h": 1,
    "openings": [
      {
        "center": 1,
        "edge": -9007199254740991,
        "frameColor": "",
        "height": 1,
        "hinge": "start",
        "id": "",
        "kind": "window",
        "leaf": "swing",
        "leafColor": "",
        "leafStyle": "flush",
        "open": true,
        "panes": 0,
        "side": "back",
        "sill": 0,
        "swing": "in",
        "width": 1
      }
    ],
    "w": 1,
    "wallColor": "",
    "wallColors": {
      "additionalProperty": ""
    }
  },
  "version": -9007199254740991
}
```

<a id="scalar-schema-layoutimportresult"></a>

### LayoutImportResult

**Type:** `object`

What a layout import saved. Beta.

- **`placed` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Pieces saved
- **`problems` (required)**: `array of string`

  Layout problems in the room as saved (pieces overlapping, a blocked door). Not an error: the layout is saved either way.
- **`room_id` (required)**: `string`

  The room the layout was saved to
- **`skipped` (required)**: `array`

  Pieces left out, for a catalog id Sunny doesn't know

  **Items:**
  - **`catalog_id` (required)**: `string`
  - **`index` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    The piece's index in `placements`
  - **`message` (required)**: `string`

<a id="scalar-example-76"></a>

**Generated example:**

```json
{
  "placed": -9007199254740991,
  "problems": [
    ""
  ],
  "room_id": "",
  "skipped": [
    {
      "catalog_id": "",
      "index": -9007199254740991,
      "message": ""
    }
  ]
}
```

<a id="scalar-schema-layoutplacement"></a>

### LayoutPlacement

**Type:** `object`

- **`catalogId` (required)**: `string`, minLength: `1`
- **`id` (required)**: `integer`, maximum: `9007199254740991`, exclusiveMinimum: `0`
- **`item` (required)**: `object`

  Informational snapshot so the document is readable without the catalog; import re-resolves from catalogId
  - **`d` (required)**: `number`
  - **`name` (required)**: `string`
  - **`w` (required)**: `number`
- **`x` (required)**: `number`
- **`y` (required)**: `number`
- **`config`**: [LayoutPlacementConfig](#scalar-schema-layoutplacementconfig)

  Round-trip placement fields (rotation, finish, attachments, …), present only when set

<a id="scalar-example-77"></a>

**Generated example:**

```json
{
  "catalogId": "",
  "config": {
    "artH": 1,
    "artW": 1,
    "attachAt": "",
    "attachT": 0,
    "attachments": [
      {
        "attachAt": "",
        "mount": "",
        "offset": {
          "x": 1,
          "y": 1,
          "yaw": 1
        },
        "parentId": 1,
        "t": 0
      }
    ],
    "doorsOpen": [
      ""
    ],
    "elevation": 1,
    "finish": "",
    "fringed": true,
    "hidden": true,
    "label": "",
    "locked": true,
    "mountH": 1,
    "on": true,
    "open": true,
    "ordered": true,
    "parentId": 1,
    "pileH": 1,
    "power": 0,
    "propParams": {
      "category": "storage",
      "daylight": 0,
      "depth": 0.005,
      "diagonal": 10,
      "fit": "contain",
      "frame": 0,
      "fringe": true,
      "front": "glass",
      "fullness": 1.3,
      "height": 0.15,
      "length": 0.1,
      "mat": 0,
      "offsetX": -1,
      "offsetY": -1,
      "opening": 0,
      "panelCount": 2,
      "panelLength": 2.1336,
      "portrait": true,
      "preset": "default",
      "ratio": "16:9",
      "shape": "rect",
      "slatAngle": -80,
      "width": 0.15,
      "windowDrop": 0.6,
      "windowTop": 0.6
    },
    "raiseT": 1,
    "raised": true,
    "rotation": 1,
    "scale": 1,
    "selectable": true,
    "size": "",
    "slotFinishes": {
      "shell": ""
    },
    "src": "",
    "suggested": true,
    "system": {
      "familyId": "",
      "presetId": "",
      "presetVersion": 1,
      "rootChildId": 1
    }
  },
  "id": 1,
  "item": {
    "d": 1,
    "name": "",
    "w": 1
  },
  "x": 1,
  "y": 1
}
```

<a id="scalar-schema-layoutplacementconfig"></a>

### LayoutPlacementConfig

**Type:** `object`

Optional round-trip fields on a layout placement. Mirrors Placement config keys; omitted keys are unset.

- **`artH`**: `number`, exclusiveMinimum: `0`
- **`artW`**: `number`, exclusiveMinimum: `0`
- **`attachAt`**: `string`
- **`attachments`**: `array`

  **Items:**
  - **`attachAt` (required)**: `string`, minLength: `1`
  - **`mount` (required)**: `string`, minLength: `1`
  - **`parentId` (required)**: `integer`, maximum: `9007199254740991`, exclusiveMinimum: `0`
  - **`offset`**: `object`
    - **`x` (required)**: `number`
    - **`y` (required)**: `number`
    - **`yaw`**: `number`
  - **`t`**: `number`, minimum: `0`, maximum: `1`
- **`attachT`**: `number`, minimum: `0`, maximum: `1`
- **`doorsOpen`**: `array of string`
- **`elevation`**: `number`
- **`finish`**: `string`
- **`fringed`**: `boolean`
- **`hidden`**: `boolean`
- **`label`**: `string`, minLength: `1`, maxLength: `80`
- **`locked`**: `boolean`
- **`mountH`**: `number`
- **`on`**: `boolean`
- **`open`**: `boolean`
- **`ordered`**: `boolean`
- **`parentId`**: `integer`, maximum: `9007199254740991`, exclusiveMinimum: `0`
- **`pileH`**: `number`
- **`power`**: `number`, minimum: `0`, maximum: `1`
- **`propParams`**: `object`, no additional properties
  - **`category`**: `string`, possible values: `"storage", "refrigerator", "stove", "bed", "sink", "washerDryer", "toilet", "bathtub", "oven", "dishwasher", "table", "sofa", "chair", "fireplace", "television", "stairs"`
  - **`daylight`**: `number`, minimum: `0`, maximum: `1`

    Approximate filtered daylight, 0 off to 1 full. Does not add a scene light.
  - **`depth`**: `number`, minimum: `0.005`, maximum: `0.12`
  - **`diagonal`**: `number`, minimum: `10`, maximum: `120`
  - **`fit`**: `string`, possible values: `"contain", "cover"`
  - **`frame`**: `number`, minimum: `0`, maximum: `0.1`
  - **`fringe`**: `boolean`
  - **`front`**: `string`, possible values: `"glass", "lowglare", "matte"`
  - **`fullness`**: `number`, minimum: `1.3`, maximum: `2.3`
  - **`height`**: `number`, minimum: `0.15`, maximum: `10`
  - **`length`**: `number`, minimum: `0.1`, maximum: `10`
  - **`mat`**: `number`, minimum: `0`, maximum: `0.2`
  - **`offsetX`**: `number`, minimum: `-1`, maximum: `1`
  - **`offsetY`**: `number`, minimum: `-1`, maximum: `1`
  - **`opening`**: `number`, minimum: `0`, maximum: `1`

    0 fully closed/lowered; 1 fully open/raised.
  - **`panelCount`**

    **Any of:**
    - `number`, const: `2`
    - `number`, const: `4`
  - **`panelLength`**: `number`, minimum: `2.1336`, maximum: `3.048`
  - **`portrait`**: `boolean`
  - **`preset`**: `string`, possible values: `"default", "fire"`
  - **`ratio`**: `string`, possible values: `"16:9", "16:10", "21:9", "32:9"`
  - **`shape`**: `string`, possible values: `"rect", "round"`
  - **`slatAngle`**: `number`, minimum: `-80`, maximum: `80`

    Slat tilt in degrees; 0 horizontal, ±80 closed. Independent of lift.
  - **`width`**: `number`, minimum: `0.15`, maximum: `10`
  - **`windowDrop`**: `number`, minimum: `0.6`, maximum: `2.35`
  - **`windowTop`**: `number`, minimum: `0.6`, maximum: `3.2`
- **`raised`**: `boolean`
- **`raiseT`**: `number`
- **`rotation`**: `number`
- **`scale`**: `number`, exclusiveMinimum: `0`
- **`selectable`**: `boolean`
- **`size`**: `string`
- **`slotFinishes`**: `object`

  **Additional properties:**

  `string`
- **`src`**: `string`
- **`suggested`**: `boolean`
- **`system`**: `object`
  - **`familyId` (required)**: `string`, minLength: `1`
  - **`rootChildId` (required)**: `integer`, maximum: `9007199254740991`, exclusiveMinimum: `0`
  - **`presetId`**: `string`
  - **`presetVersion`**: `integer`, maximum: `9007199254740991`, exclusiveMinimum: `0`

<a id="scalar-example-78"></a>

**Generated example:**

```json
{
  "artH": 1,
  "artW": 1,
  "attachAt": "",
  "attachT": 0,
  "attachments": [
    {
      "attachAt": "",
      "mount": "",
      "offset": {
        "x": 1,
        "y": 1,
        "yaw": 1
      },
      "parentId": 1,
      "t": 0
    }
  ],
  "doorsOpen": [
    ""
  ],
  "elevation": 1,
  "finish": "",
  "fringed": true,
  "hidden": true,
  "label": "",
  "locked": true,
  "mountH": 1,
  "on": true,
  "open": true,
  "ordered": true,
  "parentId": 1,
  "pileH": 1,
  "power": 0,
  "propParams": {
    "category": "storage",
    "daylight": 0,
    "depth": 0.005,
    "diagonal": 10,
    "fit": "contain",
    "frame": 0,
    "fringe": true,
    "front": "glass",
    "fullness": 1.3,
    "height": 0.15,
    "length": 0.1,
    "mat": 0,
    "offsetX": -1,
    "offsetY": -1,
    "opening": 0,
    "panelCount": 2,
    "panelLength": 2.1336,
    "portrait": true,
    "preset": "default",
    "ratio": "16:9",
    "shape": "rect",
    "slatAngle": -80,
    "width": 0.15,
    "windowDrop": 0.6,
    "windowTop": 0.6
  },
  "raiseT": 1,
  "raised": true,
  "rotation": 1,
  "scale": 1,
  "selectable": true,
  "size": "",
  "slotFinishes": {
    "shell": ""
  },
  "src": "",
  "suggested": true,
  "system": {
    "familyId": "",
    "presetId": "",
    "presetVersion": 1,
    "rootChildId": 1
  }
}
```

<a id="scalar-schema-layoutroom"></a>

### LayoutRoom

**Type:** `object`

Room shell in a sunny-layout document. Openings are always parametric; exportLayout materializes legacy windows/door/doorPos before write.

- **`d` (required)**: `number`, exclusiveMinimum: `0`

  Interior depth, meters
- **`w` (required)**: `number`, exclusiveMinimum: `0`

  Interior width, meters
- **`architecture`**: `object`
  - **`attachments` (required)**: `array`, maxItems: `2000`

    **Items:**
    - **`hostIds` (required)**: `array`, minItems: `1`, maxItems: `20`

      **Items:**

      `string`, minLength: `1`, maxLength: `200`
    - **`placementId` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`components` (required)**: `array`, minItems: `1`, maxItems: `2000`

    **Items:**
    - **`id` (required)**: `string`, minLength: `1`, maxLength: `200`
    - **`kind` (required)**: `string`, possible values: `"floor", "wall", "ceiling", "fixture", "structure"`
    - **`ownerRoomId` (required)**: `string`, minLength: `1`, maxLength: `200`
    - **`roomIds` (required)**: `array`, minItems: `1`, maxItems: `100`

      **Items:**

      `string`, minLength: `1`, maxLength: `200`
    - **`hostIds`**: `array`, maxItems: `20`

      **Items:**

      `string`, minLength: `1`, maxLength: `200`
    - **`interior`**: `boolean`
    - **`normal`**: `array`, minItems: `3`, maxItems: `3`

      **Items:**

      never (false schema)
    - **`roomNormals`**: `array`, maxItems: `100`

      **Items:**
      - **`normal` (required)**: `array`, minItems: `3`, maxItems: `3`

        **Items:**

        never (false schema)
      - **`roomId` (required)**: `string`, minLength: `1`, maxLength: `200`
  - **`modelKey` (required)**: `string`, pattern: `^(?:models\/architecture\/[a-zA-Z0-9_./-]+|space-assets\/prj_[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+)\.glb$`
  - **`origin` (required)**: `array`, minItems: `3`, maxItems: `3`

    **Items:**

    never (false schema)
  - **`revision` (required)**: `string`, minLength: `1`, maxLength: `200`
  - **`roomId` (required)**: `string`, minLength: `1`, maxLength: `200`
  - **`sourceId` (required)**: `string`, minLength: `1`, maxLength: `200`
  - **`support` (required)**: `object`
    - **`id` (required)**: `string`, minLength: `1`, maxLength: `200`
    - **`polygon` (required)**: `array`, minItems: `3`, maxItems: `2048`

      **Items:**

      minItems: `2`, maxItems: `2`

      **Array of:**

      never (false schema)
    - **`holes`**: `array`, maxItems: `100`

      **Items:**

      minItems: `3`, maxItems: `2048`

      **Array of:**

      minItems: `2`, maxItems: `2`

      **Array of:**

      never (false schema)
  - **`version` (required)**: `number`, const: `1`
- **`floorColor`**: `string`

  \#rrggbb tint overriding the finish's own color
- **`floorMaterial`**: `object`, no additional properties
  - **`baseColorKey` (required)**: `string`, maxLength: `512`, pattern: `^space-assets\/[A-Za-z0-9_/-]+\.(png|jpe?g|webp)$`
  - **`depthM` (required)**: `number`, minimum: `0.02`, maximum: `20`
  - **`widthM` (required)**: `number`, minimum: `0.02`, maximum: `20`
  - **`normalKey`**: `string`, maxLength: `512`, pattern: `^space-assets\/[A-Za-z0-9_/-]+\.(png|jpe?g|webp)$`
  - **`normalScale`**: `number`, default: `0.35`, minimum: `0`, maximum: `2`
  - **`roughness`**: `number`, default: `0.65`, minimum: `0`, maximum: `1`
  - **`roughnessKey`**: `string`, maxLength: `512`, pattern: `^space-assets\/[A-Za-z0-9_/-]+\.(png|jpe?g|webp)$`
- **`floorType`**: `string`, possible values: `"tile", "concrete", "oak", "birch", "walnut", "espresso", "plush", "oatmeal", "sage", "clay", "charcoal"`

  Present only when the finish isn't the studio's tile default
- **`footprint`**: [SpaceFootprint](#scalar-schema-spacefootprint)

  Non-rectangular room shape. Absent = the plain w×d rectangle.
- **`h`**: `number`, exclusiveMinimum: `0`
- **`openings`**: array of [WallOpening](#scalar-schema-wallopening)

  Parametric openings only. Absent/empty = a plain box.
- **`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.

  **Additional properties:**

  `string`

<a id="scalar-example-79"></a>

**Generated example:**

```json
{
  "architecture": {
    "attachments": [
      {
        "hostIds": [
          ""
        ],
        "placementId": -9007199254740991
      }
    ],
    "components": [
      {
        "hostIds": [
          ""
        ],
        "id": "",
        "interior": true,
        "kind": "floor",
        "normal": [
          1,
          1,
          1
        ],
        "ownerRoomId": "",
        "roomIds": [
          ""
        ],
        "roomNormals": [
          {
            "normal": [
              1,
              1,
              1
            ],
            "roomId": ""
          }
        ]
      }
    ],
    "modelKey": "",
    "origin": [
      1,
      1,
      1
    ],
    "revision": "",
    "roomId": "",
    "sourceId": "",
    "support": {
      "holes": [
        [
          [
            1,
            1
          ],
          [
            1,
            1
          ],
          [
            1,
            1
          ]
        ]
      ],
      "id": "",
      "polygon": [
        [
          1,
          1
        ],
        [
          1,
          1
        ],
        [
          1,
          1
        ]
      ]
    },
    "version": 1
  },
  "d": 1,
  "floorColor": "",
  "floorMaterial": {
    "baseColorKey": "",
    "depthM": 0.02,
    "normalKey": "",
    "normalScale": 0.35,
    "roughness": 0.65,
    "roughnessKey": "",
    "widthM": 0.02
  },
  "floorType": "tile",
  "footprint": {
    "cellSize": 0.1,
    "cells": [
      [
        1,
        1
      ]
    ]
  },
  "h": 1,
  "openings": [
    {
      "center": 1,
      "edge": -9007199254740991,
      "frameColor": "",
      "height": 1,
      "hinge": "start",
      "id": "",
      "kind": "window",
      "leaf": "swing",
      "leafColor": "",
      "leafStyle": "flush",
      "open": true,
      "panes": 0,
      "side": "back",
      "sill": 0,
      "swing": "in",
      "width": 1
    }
  ],
  "w": 1,
  "wallColor": "",
  "wallColors": {
    "additionalProperty": ""
  }
}
```

<a id="scalar-schema-manufacturer"></a>

### Manufacturer

**Type:** `object`

A manufacturer's public profile. Counts cover only the catalog items you can read. Beta.

- **`families` (required)**: `array`

  Product families among those items, by name

  **Items:**
  - **`item_count` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`name` (required)**: `string`

    As the catalog item's `family` spells it
- **`id` (required)**: `string`

  Opaque id (C1)
- **`item_count` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Catalog items from this manufacturer that you can read on `/v1/catalog/items`
- **`name` (required)**: `string`
- **`description`**: `string`
- **`logo_url`**: `string`
- **`slug`**: `string`

  Stable lookup key, accepted wherever `id` is
- **`website_url`**: `string`

<a id="scalar-example-80"></a>

**Generated example:**

```json
{
  "description": "",
  "families": [
    {
      "item_count": -9007199254740991,
      "name": ""
    }
  ],
  "id": "",
  "item_count": -9007199254740991,
  "logo_url": "",
  "name": "",
  "slug": "",
  "website_url": ""
}
```

<a id="scalar-schema-money"></a>

### Money

**Type:** `object`

An amount with its currency (C3).

- **`amount` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Integer, in minor units of `currency`
- **`currency` (required)**: `string`, pattern: `^[A-Z]{3}$`

  ISO 4217 currency code

<a id="scalar-example-81"></a>

**Generated example:**

```json
{
  "amount": -9007199254740991,
  "currency": "USD"
}
```

<a id="scalar-schema-orderdraft"></a>

### OrderDraft

**Type:** `object`

The quote lines an order file reads as, before any catalog matching. Money is in minor units, read as the workspace currency. Beta.

- **`format` (required)**: `string`, possible values: `"sif", "ofda_xml"`
- **`lines` (required)**: `array`

  **Items:**
  - **`options` (required)**: `array`

    **Items:**
    - **`code` (required)**: `string`
    - **`placeholder` (required)**: `boolean`

      An unselected slot the file keeps (`ON=...` / `Skipped Option`)
    - **`description`**: `string`
    - **`group`**: `string`
    - **`price_adder`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

      Price adder the file states per piece. Integer, in minor units of the quote's `currency`.
  - **`qty` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`sku` (required)**: `string`
  - **`source_line` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`catalog_code`**: `string`

    `MC` / `Catalog/Code`
  - **`description`**: `string`
  - **`list_unit`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    List price per piece as the file states it. Integer, in minor units of the quote's `currency`.
  - **`manufacturer_code`**: `string`

    `MG` / `VendorRef`

<a id="scalar-example-82"></a>

**Generated example:**

```json
{
  "format": "sif",
  "lines": [
    {
      "catalog_code": "",
      "description": "",
      "list_unit": -9007199254740991,
      "manufacturer_code": "",
      "options": [
        {
          "code": "",
          "description": "",
          "group": "",
          "placeholder": true,
          "price_adder": -9007199254740991
        }
      ],
      "qty": -9007199254740991,
      "sku": "",
      "source_line": -9007199254740991
    }
  ]
}
```

<a id="scalar-schema-orderimportline"></a>

### OrderImportLine

**Type:** `object`

One order-file line. Beta.

- **`catalog_check` (required)**: `string`, possible values: `"ok", "warn", "fail", "unverified"`

  The manufacturer catalog check: `unverified` when no catalog release for the part's manufacturer is loaded for your account.
- **`importable` (required)**: `boolean`

  Whether the line matches exactly one quotable catalog item, so the import adds it. A line that doesn't is skipped and carries an `error` issue from the `quote` check.
- **`issues` (required)**: array of [OrderIssue](#scalar-schema-orderissue)
- **`qty` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
- **`sku` (required)**: `string`

  The part number the file names
- **`source_line` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  1-based line in the file where the item starts (`PN=` or `<OrderLineItem>`)
- **`catalog_item_id`**: `string`

  The matched catalog item, when importable
- **`line_id`**: `string`

  The quote line created from it; only on a persisted import

<a id="scalar-example-83"></a>

**Generated example:**

```json
{
  "catalog_check": "ok",
  "catalog_item_id": "",
  "importable": true,
  "issues": [
    {
      "actual": "",
      "check": "file",
      "code": "sku_not_found",
      "expected": "",
      "group": "",
      "keys": [
        ""
      ],
      "message": "",
      "option": "",
      "severity": "error"
    }
  ],
  "line_id": "",
  "qty": -9007199254740991,
  "sku": "",
  "source_line": -9007199254740991
}
```

<a id="scalar-schema-orderimportpreflight"></a>

### OrderImportPreflight

**Type:** `object`

What the import found in the file, line by line. Beta.

- **`catalogs` (required)**: `array`

  The manufacturer catalog releases consulted

  **Items:**
  - **`key` (required)**: `string`
  - **`label` (required)**: `string`
- **`format` (required)**: `string`, possible values: `"sif", "ofda_xml"`
- **`issues` (required)**: array of [OrderIssue](#scalar-schema-orderissue)

  File-level findings
- **`lines` (required)**: array of [OrderImportLine](#scalar-schema-orderimportline)
- **`status` (required)**: `string`, possible values: `"pass", "warn", "fail", "unverified"`

  `fail`: at least one `error` issue. `warn`: warnings only. `unverified`: no errors or warnings, but some lines had no manufacturer catalog to check against. `pass`: none of these.
- **`summary` (required)**: `object`
  - **`catalog_checked` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Lines checked against a manufacturer catalog
  - **`errors` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`importable` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`lines` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Lines in the file
  - **`skipped` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`warnings` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

<a id="scalar-example-84"></a>

**Generated example:**

```json
{
  "catalogs": [
    {
      "key": "",
      "label": ""
    }
  ],
  "format": "sif",
  "issues": [
    {
      "actual": "",
      "check": "file",
      "code": "sku_not_found",
      "expected": "",
      "group": "",
      "keys": [
        ""
      ],
      "message": "",
      "option": "",
      "severity": "error"
    }
  ],
  "lines": [
    {
      "catalog_check": "ok",
      "catalog_item_id": "",
      "importable": true,
      "issues": [
        {
          "actual": "",
          "check": "file",
          "code": "sku_not_found",
          "expected": "",
          "group": "",
          "keys": [
            ""
          ],
          "message": "",
          "option": "",
          "severity": "error"
        }
      ],
      "line_id": "",
      "qty": -9007199254740991,
      "sku": "",
      "source_line": -9007199254740991
    }
  ],
  "status": "pass",
  "summary": {
    "catalog_checked": -9007199254740991,
    "errors": -9007199254740991,
    "importable": -9007199254740991,
    "lines": -9007199254740991,
    "skipped": -9007199254740991,
    "warnings": -9007199254740991
  }
}
```

<a id="scalar-schema-orderissue"></a>

### OrderIssue

**Type:** `object`

One finding about an order file. Beta.

- **`check` (required)**: `string`, possible values: `"file", "manufacturer_catalog", "quote"`

  Which check raised it: `file` (reading the order file), `manufacturer_catalog` (the manufacturer catalog releases loaded for your account), `quote` (matching the line to a quotable Sunny catalog item).
- **`code` (required)**: `string`

  What was found, e.g. `unknown_part`, `list_price_mismatch` (manufacturer catalog), `sku_not_found`, `list_price_differs` (quote), `missing_qty` (file). The set grows; handle codes you don't recognise by `severity`.
- **`message` (required)**: `string`
- **`severity` (required)**: `string`, possible values: `"error", "warning", "info"`
- **`actual`**: `string`

  The file's value, on a mismatch
- **`expected`**: `string`

  The catalog's value, on a mismatch
- **`group`**: `string`

  The option group involved, when known
- **`keys`**: `array of string`

  File keys (SIF) or element paths (OFDA) involved, when any
- **`option`**: `string`

  The option code involved, when one

<a id="scalar-example-85"></a>

**Generated example:**

```json
{
  "actual": "",
  "check": "file",
  "code": "sku_not_found",
  "expected": "",
  "group": "",
  "keys": [
    ""
  ],
  "message": "",
  "option": "",
  "severity": "error"
}
```

<a id="scalar-schema-presentlink"></a>

### PresentLink

**Type:** `object`

A quote's Present link. One active link per quote; addressed through its quote. Beta.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`quote_id` (required)**: `string`

  The quote this link presents
- **`status` (required)**: `string`, possible values: `"active", "revoked"`
- **`url` (required)**: `string`

  The customer-facing Present page. Treat it as a secret: anyone with the URL can view the quote.
- **`revoked_at`**: `string`

  ISO 8601, UTC

<a id="scalar-example-86"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "quote_id": "",
  "revoked_at": "2026-10-01T15:04:05.000Z",
  "status": "active",
  "url": ""
}
```

<a id="scalar-schema-presentlinksendresult"></a>

### PresentLinkSendResult

**Type:** `object`

Who a send reached. Beta.

- **`sent` (required)**: `array of string`

  Addresses queued for delivery
- **`skipped` (required)**: `array`

  Addresses not sent to this time, with the reason

  **Items:**
  - **`email` (required)**: `string`
  - **`reason` (required)**: `string`, possible values: `"throttled"`

    `throttled`: already sent this link within the last 60 seconds. New reasons may be added.

<a id="scalar-example-87"></a>

**Generated example:**

```json
{
  "sent": [
    ""
  ],
  "skipped": [
    {
      "email": "",
      "reason": "throttled"
    }
  ]
}
```

<a id="scalar-schema-project"></a>

### Project

**Type:** `object`

A project: a building or job. Beta.

- **`floor_ids` (required)**: `array of string`

  The project's floors, in order
- **`id` (required)**: `string`

  Opaque id (C1)
- **`live_editing` (required)**: `boolean`

  Whether a studio tab open on one of the project's rooms shows agent and API edits as they land
- **`members` (required)**: array of [ProjectMember](#scalar-schema-projectmember)

  The people on the project
- **`name` (required)**: `string`
- **`status` (required)**: `string`

  Free text the workspace sets, e.g. `Active`
- **`address`**: `string`
- **`pinned_at`**: `string`

  When the project was pinned to the top of the workspace's list

<a id="scalar-example-88"></a>

**Generated example:**

```json
{
  "address": "",
  "floor_ids": [
    ""
  ],
  "id": "",
  "live_editing": true,
  "members": [
    {
      "role": "owner",
      "user_id": ""
    }
  ],
  "name": "",
  "pinned_at": "2026-10-01T15:04:05.000Z",
  "status": ""
}
```

<a id="scalar-schema-projectfile"></a>

### ProjectFile

**Type:** `object`

A file in a project's Library: a photo, document or 3D model, project-wide or one room's own. Beta.

- **`content_type` (required)**: `string`

  Media type, e.g. `application/pdf`
- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`kind` (required)**: `string`, possible values: `"image", "file", "model"`

  `image` for a photo or picture, `model` for a 3D model, `file` for the rest
- **`name` (required)**: `string`
- **`url` (required)**: `string`

  Where to download the file
- **`room_id`**: `string`

  The room the file belongs to; absent for a project-wide file
- **`size`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  Bytes

<a id="scalar-example-89"></a>

**Generated example:**

```json
{
  "content_type": "",
  "created_at": "2026-10-01T15:04:05.000Z",
  "id": "",
  "kind": "image",
  "name": "",
  "room_id": "",
  "size": 0,
  "url": ""
}
```

<a id="scalar-schema-projectfilelist"></a>

### ProjectFileList

**Type:** `object`

- **`data` (required)**: array of [ProjectFile](#scalar-schema-projectfile)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-90"></a>

**Generated example:**

```json
{
  "data": [
    {
      "content_type": "",
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "kind": "image",
      "name": "",
      "room_id": "",
      "size": 0,
      "url": ""
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-projectlist"></a>

### ProjectList

**Type:** `object`

- **`data` (required)**: array of [Project](#scalar-schema-project)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-91"></a>

**Generated example:**

```json
{
  "data": [
    {
      "address": "",
      "floor_ids": [
        ""
      ],
      "id": "",
      "live_editing": true,
      "members": [
        {
          "role": "owner",
          "user_id": ""
        }
      ],
      "name": "",
      "pinned_at": "2026-10-01T15:04:05.000Z",
      "status": ""
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-projectmember"></a>

### ProjectMember

**Type:** `object`

A person on a project. Beta.

- **`user_id` (required)**: `string`

  The member's Sunny user id
- **`role`**: `string`, possible values: `"owner", "editor", "reviewer", "viewer"`

  Their role on the project; absent when none is set

<a id="scalar-example-92"></a>

**Generated example:**

```json
{
  "role": "owner",
  "user_id": ""
}
```

<a id="scalar-schema-quote"></a>

### Quote

**Type:** `object`

A quote. Lines are a sub-resource (`/v1/quotes/{id}/lines`), not embedded.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`currency` (required)**: `string`, pattern: `^[A-Z]{3}$`

  ISO 4217 code every money field on the quote and its lines is in. Fixed when the quote is created. Read-only.
- **`customer_id` (required)**: `string`

  The customer this quote is for
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`status` (required)**: `string`, possible values: `"draft", "presented", "accepted", "archived"`

  `accepted` is reserved and not set yet. New values may be added; handle values you don't recognise.
- **`totals` (required)**: [QuoteTotals](#scalar-schema-quotetotals)

  Computed by the same calculation as the Present page, the PDF and the order SIF.
- **`updated_at` (required)**: `string`

  ISO 8601, UTC
- **`discount_table_revision_id`**: `string`

  The discount table revision that prices the quote's catalog lines. Present only when the caller holds `quote_costs:read`.
- **`number`**: `string`

  Per-workspace document number, e.g. `Q-000123`. Read-only.

<a id="scalar-example-93"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "currency": "USD",
  "customer_id": "",
  "discount_table_revision_id": "",
  "id": "",
  "name": "",
  "number": "Q-000123",
  "status": "draft",
  "totals": {
    "buy_total": -9007199254740991,
    "line_count": -9007199254740991,
    "list_total": -9007199254740991,
    "margin": -9007199254740991,
    "margin_percent": 1,
    "sell_total": -9007199254740991
  },
  "updated_at": "2026-10-01T15:04:05.000Z"
}
```

<a id="scalar-schema-quoteimportdryrun"></a>

### QuoteImportDryRun

**Type:** `object`

A dry run: nothing was persisted. Beta.

- **`draft` (required)**: [OrderDraft](#scalar-schema-orderdraft)

  The quote lines an order file reads as, before any catalog matching. Money is in minor units, read as the workspace currency. Beta.
- **`preflight` (required)**: [OrderImportPreflight](#scalar-schema-orderimportpreflight)

  What the import found in the file, line by line. Beta.

<a id="scalar-example-94"></a>

**Generated example:**

```json
{
  "draft": {
    "format": "sif",
    "lines": [
      {
        "catalog_code": "",
        "description": "",
        "list_unit": -9007199254740991,
        "manufacturer_code": "",
        "options": [
          {
            "code": "",
            "description": "",
            "group": "",
            "placeholder": true,
            "price_adder": -9007199254740991
          }
        ],
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ]
  },
  "preflight": {
    "catalogs": [
      {
        "key": "",
        "label": ""
      }
    ],
    "format": "sif",
    "issues": [
      {
        "actual": "",
        "check": "file",
        "code": "sku_not_found",
        "expected": "",
        "group": "",
        "keys": [
          ""
        ],
        "message": "",
        "option": "",
        "severity": "error"
      }
    ],
    "lines": [
      {
        "catalog_check": "ok",
        "catalog_item_id": "",
        "importable": true,
        "issues": [
          {
            "actual": "",
            "check": "file",
            "code": "sku_not_found",
            "expected": "",
            "group": "",
            "keys": [
              ""
            ],
            "message": "",
            "option": "",
            "severity": "error"
          }
        ],
        "line_id": "",
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ],
    "status": "pass",
    "summary": {
      "catalog_checked": -9007199254740991,
      "errors": -9007199254740991,
      "importable": -9007199254740991,
      "lines": -9007199254740991,
      "skipped": -9007199254740991,
      "warnings": -9007199254740991
    }
  }
}
```

<a id="scalar-schema-quoteimportresult"></a>

### QuoteImportResult

**Type:** `object`

A persisted import. Beta.

- **`preflight` (required)**: [OrderImportPreflight](#scalar-schema-orderimportpreflight)

  What the import found in the file, line by line. Beta.
- **`quote` (required)**: [Quote](#scalar-schema-quote)

  A quote. Lines are a sub-resource (`/v1/quotes/{id}/lines`), not embedded.

<a id="scalar-example-95"></a>

**Generated example:**

```json
{
  "preflight": {
    "catalogs": [
      {
        "key": "",
        "label": ""
      }
    ],
    "format": "sif",
    "issues": [
      {
        "actual": "",
        "check": "file",
        "code": "sku_not_found",
        "expected": "",
        "group": "",
        "keys": [
          ""
        ],
        "message": "",
        "option": "",
        "severity": "error"
      }
    ],
    "lines": [
      {
        "catalog_check": "ok",
        "catalog_item_id": "",
        "importable": true,
        "issues": [
          {
            "actual": "",
            "check": "file",
            "code": "sku_not_found",
            "expected": "",
            "group": "",
            "keys": [
              ""
            ],
            "message": "",
            "option": "",
            "severity": "error"
          }
        ],
        "line_id": "",
        "qty": -9007199254740991,
        "sku": "",
        "source_line": -9007199254740991
      }
    ],
    "status": "pass",
    "summary": {
      "catalog_checked": -9007199254740991,
      "errors": -9007199254740991,
      "importable": -9007199254740991,
      "lines": -9007199254740991,
      "skipped": -9007199254740991,
      "warnings": -9007199254740991
    }
  },
  "quote": {
    "created_at": "2026-10-01T15:04:05.000Z",
    "currency": "USD",
    "customer_id": "",
    "discount_table_revision_id": "",
    "id": "",
    "name": "",
    "number": "Q-000123",
    "status": "draft",
    "totals": {
      "buy_total": -9007199254740991,
      "line_count": -9007199254740991,
      "list_total": -9007199254740991,
      "margin": -9007199254740991,
      "margin_percent": 1,
      "sell_total": -9007199254740991
    },
    "updated_at": "2026-10-01T15:04:05.000Z"
  }
}
```

<a id="scalar-schema-quoteline"></a>

### QuoteLine

**Type:** `object`

One priced row on a quote.

- **`id` (required)**: `string`

  Opaque id (C1)
- **`kind` (required)**: `string`, possible values: `"catalog", "adhoc"`

  `catalog`: a catalog product. `adhoc`: a typed-in charge (freight, installation) with a `description` and no catalog reference.
- **`list_unit` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Catalog list price per piece. Integer, in minor units of the quote's `currency`.
- **`options` (required)**: array of [QuoteLineOption](#scalar-schema-quotelineoption)

  Selected options; `[]` for a single-configuration SKU. Objects may gain fields. Beta.
- **`position` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sort order within the quote
- **`qty` (required)**: `integer`, minimum: `1`, maximum: `9007199254740991`
- **`quote_id` (required)**: `string`

  The quote this line belongs to
- **`sell_unit` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Customer price per piece. Integer, in minor units of the quote's `currency`.
- **`applied_rule_id`**: `string`

  The discount rule that priced this line. Present only when the caller holds `quote_costs:read`.
- **`buy_unit`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Dealer cost per piece. Present only when the caller holds `quote_costs:read`. Integer, in minor units of the quote's `currency`.
- **`catalog_item_id`**: `string`

  The catalog item, on a catalog line when known
- **`description`**: `string`

  The printed text of an ad-hoc line
- **`sku`**: `string`

  Manufacturer part number, on a catalog line when known

<a id="scalar-example-96"></a>

**Generated example:**

```json
{
  "applied_rule_id": "",
  "buy_unit": -9007199254740991,
  "catalog_item_id": "",
  "description": "",
  "id": "",
  "kind": "catalog",
  "list_unit": -9007199254740991,
  "options": [
    {
      "code": "",
      "description": "",
      "group": "",
      "price_adder": -9007199254740991
    }
  ],
  "position": -9007199254740991,
  "qty": 1,
  "quote_id": "",
  "sell_unit": -9007199254740991,
  "sku": ""
}
```

<a id="scalar-schema-quotelinelist"></a>

### QuoteLineList

**Type:** `object`

- **`data` (required)**: array of [QuoteLine](#scalar-schema-quoteline)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-97"></a>

**Generated example:**

```json
{
  "data": [
    {
      "applied_rule_id": "",
      "buy_unit": -9007199254740991,
      "catalog_item_id": "",
      "description": "",
      "id": "",
      "kind": "catalog",
      "list_unit": -9007199254740991,
      "options": [
        {
          "code": "",
          "description": "",
          "group": "",
          "price_adder": -9007199254740991
        }
      ],
      "position": -9007199254740991,
      "qty": 1,
      "quote_id": "",
      "sell_unit": -9007199254740991,
      "sku": ""
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-quotelineoption"></a>

### QuoteLineOption

**Type:** `object`

One selected option, as exported to Order SIF. Beta.

- **`code` (required)**: `string`

  Manufacturer option code
- **`description`**: `string`
- **`group`**: `string`
- **`price_adder`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Price this option adds per piece. Integer, in minor units of the quote's `currency`.

<a id="scalar-example-98"></a>

**Generated example:**

```json
{
  "code": "",
  "description": "",
  "group": "",
  "price_adder": -9007199254740991
}
```

<a id="scalar-schema-quotelist"></a>

### QuoteList

**Type:** `object`

- **`data` (required)**: array of [Quote](#scalar-schema-quote)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-99"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "currency": "USD",
      "customer_id": "",
      "discount_table_revision_id": "",
      "id": "",
      "name": "",
      "number": "Q-000123",
      "status": "draft",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      },
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-quoteorder"></a>

### QuoteOrder

**Type:** `object`

The order a quote produces, as the order form prints it: list and customer prices, never dealer cost. Beta.

- **`currency` (required)**: `string`, pattern: `^[A-Z]{3}$`

  ISO 4217 currency code
- **`date` (required)**: `string`

  As printed on the order form
- **`footnotes` (required)**: `array of string`

  Lines the order file can't carry (ad-hoc charges have no part number)
- **`lines` (required)**: `array`

  **Items:**
  - **`amount` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    `sell_unit × qty`. Integer, in minor units of the quote's `currency`.
  - **`kind` (required)**: `string`, possible values: `"catalog", "adhoc"`
  - **`list_unit` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    List price per piece. Integer, in minor units of the quote's `currency`.
  - **`n` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Printed line number
  - **`name` (required)**: `string`
  - **`qty` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`sell_unit` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

    Customer price per piece. Integer, in minor units of the quote's `currency`.
  - **`dims`**: `string`
  - **`part`**: `string`

    Part number; absent on ad-hoc lines
  - **`room`**: `string`

    The room the line is allotted to
- **`list_total` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sum of list. Integer, in minor units of the quote's `currency`.
- **`quote_id` (required)**: `string`

  The quote the order is built from
- **`savings` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  `list_total - sell_total`. Integer, in minor units of the quote's `currency`.
- **`sell_total` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sum of sell: what the customer pays. Integer, in minor units of the quote's `currency`.
- **`title` (required)**: `string`
- **`total_qty` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
- **`customer_name`**: `string`
- **`notes`**: `string`
- **`number`**: `string`
- **`po_reference`**: `string`
- **`valid_until`**: `string`

  As printed on the order form

<a id="scalar-example-100"></a>

**Generated example:**

```json
{
  "currency": "USD",
  "customer_name": "",
  "date": "",
  "footnotes": [
    ""
  ],
  "lines": [
    {
      "amount": -9007199254740991,
      "dims": "",
      "kind": "catalog",
      "list_unit": -9007199254740991,
      "n": -9007199254740991,
      "name": "",
      "part": "",
      "qty": -9007199254740991,
      "room": "",
      "sell_unit": -9007199254740991
    }
  ],
  "list_total": -9007199254740991,
  "notes": "",
  "number": "",
  "po_reference": "",
  "quote_id": "",
  "savings": -9007199254740991,
  "sell_total": -9007199254740991,
  "title": "",
  "total_qty": -9007199254740991,
  "valid_until": ""
}
```

<a id="scalar-schema-quotetotals"></a>

### QuoteTotals

**Type:** `object`

Computed by the same calculation as the Present page, the PDF and the order SIF.

- **`line_count` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Number of lines on the quote
- **`list_total` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sum of each line's `list_unit × qty`. Integer, in minor units of the quote's `currency`.
- **`sell_total` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sum of each line's `sell_unit × qty`: what the customer pays. Integer, in minor units of the quote's `currency`.
- **`buy_total`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Sum of each line's `buy_unit × qty`: dealer cost. Present only when the caller holds `quote_costs:read`. Integer, in minor units of the quote's `currency`.
- **`margin`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  `sell_total - buy_total`. Present only when the caller holds `quote_costs:read`. Integer, in minor units of the quote's `currency`.
- **`margin_percent`**: `number`

  `margin / sell_total × 100`, two decimals; 0 when `sell_total` is 0. Present only when the caller holds `quote_costs:read`.

<a id="scalar-example-101"></a>

**Generated example:**

```json
{
  "buy_total": -9007199254740991,
  "line_count": -9007199254740991,
  "list_total": -9007199254740991,
  "margin": -9007199254740991,
  "margin_percent": 1,
  "sell_total": -9007199254740991
}
```

<a id="scalar-schema-quoteversion"></a>

### QuoteVersion

**Type:** `object`

A presented snapshot of a quote: what the customer saw on the Present page at that version. Beta.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`lines` (required)**: array of [QuoteLine](#scalar-schema-quoteline)

  The lines as presented, in the `QuoteLine` shape. Cost fields follow the same `quote_costs:read` rule as the live lines.
- **`number` (required)**: `integer`, minimum: `1`, maximum: `9007199254740991`

  1, 2, 3… per quote
- **`quote_id` (required)**: `string`

  The quote this version snapshots
- **`totals` (required)**: [QuoteTotals](#scalar-schema-quotetotals)

  Computed by the same calculation as the Present page, the PDF and the order SIF.

<a id="scalar-example-102"></a>

**Generated example:**

```json
{
  "created_at": "2026-10-01T15:04:05.000Z",
  "id": "",
  "lines": [
    {
      "applied_rule_id": "",
      "buy_unit": -9007199254740991,
      "catalog_item_id": "",
      "description": "",
      "id": "",
      "kind": "catalog",
      "list_unit": -9007199254740991,
      "options": [
        {
          "code": "",
          "description": "",
          "group": "",
          "price_adder": -9007199254740991
        }
      ],
      "position": -9007199254740991,
      "qty": 1,
      "quote_id": "",
      "sell_unit": -9007199254740991,
      "sku": ""
    }
  ],
  "number": 1,
  "quote_id": "",
  "totals": {
    "buy_total": -9007199254740991,
    "line_count": -9007199254740991,
    "list_total": -9007199254740991,
    "margin": -9007199254740991,
    "margin_percent": 1,
    "sell_total": -9007199254740991
  }
}
```

<a id="scalar-schema-quoteversionlist"></a>

### QuoteVersionList

**Type:** `object`

- **`data` (required)**: array of [QuoteVersion](#scalar-schema-quoteversion)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-103"></a>

**Generated example:**

```json
{
  "data": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "lines": [
        {
          "applied_rule_id": "",
          "buy_unit": -9007199254740991,
          "catalog_item_id": "",
          "description": "",
          "id": "",
          "kind": "catalog",
          "list_unit": -9007199254740991,
          "options": [
            {
              "code": "",
              "description": "",
              "group": "",
              "price_adder": -9007199254740991
            }
          ],
          "position": -9007199254740991,
          "qty": 1,
          "quote_id": "",
          "sell_unit": -9007199254740991,
          "sku": ""
        }
      ],
      "number": 1,
      "quote_id": "",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      }
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-rect"></a>

### Rect

**Type:** `object`

A rectangle on the floor plate. Beta.

- **`depth` (required)**: `number`

  Depth (y), meters
- **`width` (required)**: `number`

  Width (x), meters
- **`x` (required)**: `number`

  Left edge on the floor plate, meters
- **`y` (required)**: `number`

  Top edge on the floor plate, meters

<a id="scalar-example-104"></a>

**Generated example:**

```json
{
  "depth": 1,
  "width": 1,
  "x": 1,
  "y": 1
}
```

<a id="scalar-schema-room"></a>

### Room

**Type:** `object`

A room on a floor. Its furniture is the room's layout (`/v1/rooms/{id}/layout`). Beta.

- **`depth` (required)**: `number`

  Interior depth (y), meters
- **`floor_id` (required)**: `string`

  The floor the room is on
- **`hide_room` (required)**: `boolean`

  Whether the studio hides the room's walls and floor, showing only its furniture
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`target_seats` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  How many seats the room should hold
- **`version_count` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

  How many versions of the room's layout are saved in its history
- **`width` (required)**: `number`

  Interior width (x), meters
- **`x` (required)**: `number`

  Left edge on the floor plate, meters
- **`y` (required)**: `number`

  Top edge on the floor plate, meters
- **`brief`**: `string`

  What the room is for, in words; the layout agent reads it
- **`floor_rotation`**

  Turns the floor finish's pattern, in degrees

  **Any of:**
  - `number`, const: `0`
  - `number`, const: `90`
- **`footprint`**: [RoomFootprint](#scalar-schema-roomfootprint)

  A room's outline as grid cells, for a room that isn't a plain rectangle. Beta.
- **`height`**: `number`

  Wall height, meters
- **`wainscot`**: [Wainscot](#scalar-schema-wainscot)

  Wall panelling from the floor up. Beta.
- **`wall_trim`**: [WallTrim](#scalar-schema-walltrim)

  Mouldings along a room's walls, one key per kind of trim. Beta.

<a id="scalar-example-105"></a>

**Generated example:**

```json
{
  "brief": "",
  "depth": 1,
  "floor_id": "",
  "floor_rotation": 0,
  "footprint": {
    "cell_size": 1,
    "cells": [
      [
        -9007199254740991,
        -9007199254740991
      ]
    ]
  },
  "height": 1,
  "hide_room": true,
  "id": "",
  "name": "",
  "target_seats": -9007199254740991,
  "version_count": 0,
  "wainscot": {
    "color": "",
    "height": 1,
    "sides": [
      "back"
    ]
  },
  "wall_trim": {
    "baseboard": {
      "color": "",
      "style": "classic"
    },
    "chair": {
      "color": "",
      "height": 1
    },
    "crown": {
      "color": "",
      "style": "simple"
    },
    "picture": {
      "color": "",
      "drop": 1
    }
  },
  "width": 1,
  "x": 1,
  "y": 1
}
```

<a id="scalar-schema-roomfootprint"></a>

### RoomFootprint

**Type:** `object`

A room's outline as grid cells, for a room that isn't a plain rectangle. Beta.

- **`cell_size` (required)**: `number`, exclusiveMinimum: `0`

  Grid cell edge, meters
- **`cells` (required)**: `array`

  Filled cells as \[column, row], from the room's top-left corner

  **Items:**

  minItems: `2`, maxItems: `2`

  **Array of:**

  `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

<a id="scalar-example-106"></a>

**Generated example:**

```json
{
  "cell_size": 1,
  "cells": [
    [
      -9007199254740991,
      -9007199254740991
    ]
  ]
}
```

<a id="scalar-schema-roomlist"></a>

### RoomList

**Type:** `object`

- **`data` (required)**: array of [Room](#scalar-schema-room)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-107"></a>

**Generated example:**

```json
{
  "data": [
    {
      "brief": "",
      "depth": 1,
      "floor_id": "",
      "floor_rotation": 0,
      "footprint": {
        "cell_size": 1,
        "cells": [
          [
            -9007199254740991,
            -9007199254740991
          ]
        ]
      },
      "height": 1,
      "hide_room": true,
      "id": "",
      "name": "",
      "target_seats": -9007199254740991,
      "version_count": 0,
      "wainscot": {
        "color": "",
        "height": 1,
        "sides": [
          "back"
        ]
      },
      "wall_trim": {
        "baseboard": {
          "color": "",
          "style": "classic"
        },
        "chair": {
          "color": "",
          "height": 1
        },
        "crown": {
          "color": "",
          "style": "simple"
        },
        "picture": {
          "color": "",
          "drop": 1
        }
      },
      "width": 1,
      "x": 1,
      "y": 1
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-roomversion"></a>

### RoomVersion

**Type:** `object`

One saved version of a room's layout. Beta.

- **`created_at` (required)**: `string`

  ISO 8601, UTC
- **`id` (required)**: `string`

  Opaque id (C1)
- **`item_count` (required)**: `integer`, minimum: `0`, maximum: `9007199254740991`

  How many pieces it places
- **`status` (required)**: `string`, possible values: `"done", "fallback", "manual"`

  `done` came from the layout agent, `fallback` from the keyless heuristic, `manual` from a saved edit or import
- **`brief`**: `string`

  The brief the version was made from
- **`name`**: `string`

  The version's name, when it has one
- **`parent_id`**: `string`

  The version this one refined, when it was a refinement

<a id="scalar-example-108"></a>

**Generated example:**

```json
{
  "brief": "",
  "created_at": "2026-10-01T15:04:05.000Z",
  "id": "",
  "item_count": 0,
  "name": "",
  "parent_id": "",
  "status": "done"
}
```

<a id="scalar-schema-roomversionlist"></a>

### RoomVersionList

**Type:** `object`

- **`data` (required)**: array of [RoomVersion](#scalar-schema-roomversion)
- **`next_cursor`**: `string`

  Pass as `cursor` for the next page; omitted on the last page

<a id="scalar-example-109"></a>

**Generated example:**

```json
{
  "data": [
    {
      "brief": "",
      "created_at": "2026-10-01T15:04:05.000Z",
      "id": "",
      "item_count": 0,
      "name": "",
      "parent_id": "",
      "status": "done"
    }
  ],
  "next_cursor": ""
}
```

<a id="scalar-schema-searchfamily"></a>

### SearchFamily

**Type:** `object`

A product family a search found. Beta.

- **`items` (required)**: array of [CatalogItem](#scalar-schema-catalogitem)

  The family's pieces
- **`key` (required)**: `string`

  The family's key: maker and family name
- **`name` (required)**: `string`
- **`manufacturer`**: `string`

<a id="scalar-example-110"></a>

**Generated example:**

```json
{
  "items": [
    {
      "agent_note": "",
      "category": "table",
      "description": "",
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "family": "",
      "finishes": [
        {
          "color": "#8a6a4f",
          "material": "",
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "id": "",
      "image_url": "",
      "internal_note": "",
      "list_price": {
        "amount": -9007199254740991,
        "currency": "USD"
      },
      "manufacturer": "",
      "model_number": "",
      "model_takes_finish_color": true,
      "model_url": "",
      "name": "",
      "placement": {
        "color": "",
        "flags": [
          ""
        ],
        "placeholder": true,
        "prop": {
          "defaults": {
            "additionalProperty": null
          },
          "fields": [
            ""
          ],
          "kind": "",
          "schema": {
            "additionalProperty": null
          }
        },
        "seats": -9007199254740991,
        "shape": "rect"
      },
      "plan_symbol": "manufacturer",
      "reference_photos": [
        {
          "license": "",
          "scope": "exact",
          "source": "",
          "url": ""
        }
      ],
      "retired": true,
      "seat_type": "task",
      "sizes": [
        {
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "sku": ""
    }
  ],
  "key": "",
  "manufacturer": "",
  "name": ""
}
```

<a id="scalar-schema-searchproject"></a>

### SearchProject

**Type:** `object`

A project a search found. Beta.

- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`

<a id="scalar-example-111"></a>

**Generated example:**

```json
{
  "id": "",
  "name": ""
}
```

<a id="scalar-schema-searchresult"></a>

### SearchResult

**Type:** `object`

Matches in each section. A section your scopes don't cover, or that `include` leaves out, is an empty list. Beta.

- **`customers` (required)**: array of [Customer](#scalar-schema-customer)

  Customers by name or email
- **`families` (required)**: array of [SearchFamily](#scalar-schema-searchfamily)

  Families by name or maker
- **`items` (required)**: array of [CatalogItem](#scalar-schema-catalogitem)

  The best-matching catalog items, by name or SKU
- **`projects` (required)**: array of [SearchProject](#scalar-schema-searchproject)

  Projects by name, pinned first
- **`quotes` (required)**: array of [Quote](#scalar-schema-quote)

  Quotes by name, number or customer name, newest edit first
- **`rooms` (required)**: array of [SearchRoom](#scalar-schema-searchroom)

  Rooms whose name or project's name matches
- **`typicals` (required)**: array of [SearchTypical](#scalar-schema-searchtypical)

  Typicals by name, code (`T100225`) or tag

<a id="scalar-example-112"></a>

**Generated example:**

```json
{
  "customers": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "email": "",
      "id": "",
      "name": "",
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "families": [
    {
      "items": [
        {
          "agent_note": "",
          "category": "table",
          "description": "",
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "family": "",
          "finishes": [
            {
              "color": "#8a6a4f",
              "material": "",
              "name": "",
              "price_adder": {
                "amount": -9007199254740991,
                "currency": "USD"
              }
            }
          ],
          "id": "",
          "image_url": "",
          "internal_note": "",
          "list_price": {
            "amount": -9007199254740991,
            "currency": "USD"
          },
          "manufacturer": "",
          "model_number": "",
          "model_takes_finish_color": true,
          "model_url": "",
          "name": "",
          "placement": {
            "color": "",
            "flags": [
              ""
            ],
            "placeholder": true,
            "prop": {
              "defaults": {
                "additionalProperty": null
              },
              "fields": [
                ""
              ],
              "kind": "",
              "schema": {
                "additionalProperty": null
              }
            },
            "seats": -9007199254740991,
            "shape": "rect"
          },
          "plan_symbol": "manufacturer",
          "reference_photos": [
            {
              "license": "",
              "scope": "exact",
              "source": "",
              "url": ""
            }
          ],
          "retired": true,
          "seat_type": "task",
          "sizes": [
            {
              "dimensions": {
                "depth": 1,
                "height": 1,
                "width": 1
              },
              "name": "",
              "price_adder": {
                "amount": -9007199254740991,
                "currency": "USD"
              }
            }
          ],
          "sku": ""
        }
      ],
      "key": "",
      "manufacturer": "",
      "name": ""
    }
  ],
  "items": [
    {
      "agent_note": "",
      "category": "table",
      "description": "",
      "dimensions": {
        "depth": 1,
        "height": 1,
        "width": 1
      },
      "family": "",
      "finishes": [
        {
          "color": "#8a6a4f",
          "material": "",
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "id": "",
      "image_url": "",
      "internal_note": "",
      "list_price": {
        "amount": -9007199254740991,
        "currency": "USD"
      },
      "manufacturer": "",
      "model_number": "",
      "model_takes_finish_color": true,
      "model_url": "",
      "name": "",
      "placement": {
        "color": "",
        "flags": [
          ""
        ],
        "placeholder": true,
        "prop": {
          "defaults": {
            "additionalProperty": null
          },
          "fields": [
            ""
          ],
          "kind": "",
          "schema": {
            "additionalProperty": null
          }
        },
        "seats": -9007199254740991,
        "shape": "rect"
      },
      "plan_symbol": "manufacturer",
      "reference_photos": [
        {
          "license": "",
          "scope": "exact",
          "source": "",
          "url": ""
        }
      ],
      "retired": true,
      "seat_type": "task",
      "sizes": [
        {
          "dimensions": {
            "depth": 1,
            "height": 1,
            "width": 1
          },
          "name": "",
          "price_adder": {
            "amount": -9007199254740991,
            "currency": "USD"
          }
        }
      ],
      "sku": ""
    }
  ],
  "projects": [
    {
      "id": "",
      "name": ""
    }
  ],
  "quotes": [
    {
      "created_at": "2026-10-01T15:04:05.000Z",
      "currency": "USD",
      "customer_id": "",
      "discount_table_revision_id": "",
      "id": "",
      "name": "",
      "number": "Q-000123",
      "status": "draft",
      "totals": {
        "buy_total": -9007199254740991,
        "line_count": -9007199254740991,
        "list_total": -9007199254740991,
        "margin": -9007199254740991,
        "margin_percent": 1,
        "sell_total": -9007199254740991
      },
      "updated_at": "2026-10-01T15:04:05.000Z"
    }
  ],
  "rooms": [
    {
      "depth": 1,
      "floor_id": "",
      "floor_name": "",
      "id": "",
      "name": "",
      "project_id": "",
      "project_name": "",
      "width": 1
    }
  ],
  "typicals": [
    {
      "family": "",
      "id": "",
      "image_url": "",
      "manufacturer": "",
      "name": "",
      "parts": [
        {
          "count": -9007199254740991,
          "item": {
            "agent_note": "",
            "category": "table",
            "description": "",
            "dimensions": {
              "depth": 1,
              "height": 1,
              "width": 1
            },
            "family": "",
            "finishes": [
              {
                "color": "#8a6a4f",
                "material": "",
                "name": "",
                "price_adder": {
                  "amount": -9007199254740991,
                  "currency": "USD"
                }
              }
            ],
            "id": "",
            "image_url": "",
            "internal_note": "",
            "list_price": {
              "amount": -9007199254740991,
              "currency": "USD"
            },
            "manufacturer": "",
            "model_number": "",
            "model_takes_finish_color": true,
            "model_url": "",
            "name": "",
            "placement": {
              "color": "",
              "flags": [
                ""
              ],
              "placeholder": true,
              "prop": {
                "defaults": {
                  "additionalProperty": null
                },
                "fields": [
                  ""
                ],
                "kind": "",
                "schema": {
                  "additionalProperty": null
                }
              },
              "seats": -9007199254740991,
              "shape": "rect"
            },
            "plan_symbol": "manufacturer",
            "reference_photos": [
              {
                "license": "",
                "scope": "exact",
                "source": "",
                "url": ""
              }
            ],
            "retired": true,
            "seat_type": "task",
            "sizes": [
              {
                "dimensions": {
                  "depth": 1,
                  "height": 1,
                  "width": 1
                },
                "name": "",
                "price_adder": {
                  "amount": -9007199254740991,
                  "currency": "USD"
                }
              }
            ],
            "sku": ""
          }
        }
      ],
      "tags": [
        ""
      ]
    }
  ]
}
```

<a id="scalar-schema-searchroom"></a>

### SearchRoom

**Type:** `object`

A room a search found. Beta.

- **`depth` (required)**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior depth, meters
- **`floor_id` (required)**: `string`

  The floor the room is on
- **`id` (required)**: `string`

  Opaque id (C1)
- **`name` (required)**: `string`
- **`project_id` (required)**: `string`

  The room's project
- **`project_name` (required)**: `string`
- **`width` (required)**: `number`, maximum: `1000`, exclusiveMinimum: `0`

  Interior width, meters
- **`floor_name`**: `string`

<a id="scalar-example-113"></a>

**Generated example:**

```json
{
  "depth": 1,
  "floor_id": "",
  "floor_name": "",
  "id": "",
  "name": "",
  "project_id": "",
  "project_name": "",
  "width": 1
}
```

<a id="scalar-schema-searchtypical"></a>

### SearchTypical

**Type:** `object`

A typical (a manufacturer's preset workstation or setting) you may place. Beta.

- **`family` (required)**: `string`
- **`id` (required)**: `string`

  The typical's slug, which carries its code
- **`manufacturer` (required)**: `string`
- **`name` (required)**: `string`
- **`parts` (required)**: `array`

  Its distinct pieces with how many of each, in part order

  **Items:**
  - **`count` (required)**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`
  - **`item` (required)**: [CatalogItem](#scalar-schema-catalogitem)

    A catalog product. Optional sections come with `include`; notes depend on your scopes.
- **`tags` (required)**: `array of string`
- **`image_url`**: `string`

  The typical's thumbnail

<a id="scalar-example-114"></a>

**Generated example:**

```json
{
  "family": "",
  "id": "",
  "image_url": "",
  "manufacturer": "",
  "name": "",
  "parts": [
    {
      "count": -9007199254740991,
      "item": {
        "agent_note": "",
        "category": "table",
        "description": "",
        "dimensions": {
          "depth": 1,
          "height": 1,
          "width": 1
        },
        "family": "",
        "finishes": [
          {
            "color": "#8a6a4f",
            "material": "",
            "name": "",
            "price_adder": {
              "amount": -9007199254740991,
              "currency": "USD"
            }
          }
        ],
        "id": "",
        "image_url": "",
        "internal_note": "",
        "list_price": {
          "amount": -9007199254740991,
          "currency": "USD"
        },
        "manufacturer": "",
        "model_number": "",
        "model_takes_finish_color": true,
        "model_url": "",
        "name": "",
        "placement": {
          "color": "",
          "flags": [
            ""
          ],
          "placeholder": true,
          "prop": {
            "defaults": {
              "additionalProperty": null
            },
            "fields": [
              ""
            ],
            "kind": "",
            "schema": {
              "additionalProperty": null
            }
          },
          "seats": -9007199254740991,
          "shape": "rect"
        },
        "plan_symbol": "manufacturer",
        "reference_photos": [
          {
            "license": "",
            "scope": "exact",
            "source": "",
            "url": ""
          }
        ],
        "retired": true,
        "seat_type": "task",
        "sizes": [
          {
            "dimensions": {
              "depth": 1,
              "height": 1,
              "width": 1
            },
            "name": "",
            "price_adder": {
              "amount": -9007199254740991,
              "currency": "USD"
            }
          }
        ],
        "sku": ""
      }
    }
  ],
  "tags": [
    ""
  ]
}
```

<a id="scalar-schema-spacefootprint"></a>

### SpaceFootprint

**Type:** `object`

Non-rectangular room shape. Absent = the plain w×d rectangle.

- **`cells` (required)**: `array`

  \[col, row] pairs, already shifted to a 0,0 origin

  **Items:**

  minItems: `2`, maxItems: `2`

  **Array of:**

  never (false schema)
- **`cellSize` (required)**

  **Any of:**
  - `number`, const: `0.1`
  - `number`, const: `0.25`
  - `number`, const: `0.5`
  - `number`, const: `1`
  - `number`, const: `2`

<a id="scalar-example-115"></a>

**Generated example:**

```json
{
  "cellSize": 0.1,
  "cells": [
    [
      1,
      1
    ]
  ]
}
```

<a id="scalar-schema-wainscot"></a>

### Wainscot

**Type:** `object`

Wall panelling from the floor up. Beta.

- **`height` (required)**: `number`

  Top of the panelling above the floor, meters
- **`color`**: `string`

  Panel paint; absent means the wall paint, a shade lighter, as #rrggbb
- **`sides`**: `array`

  The walls that carry it; absent means every wall

  **Items:**

  `string`, possible values: `"back", "front", "left", "right"`

<a id="scalar-example-116"></a>

**Generated example:**

```json
{
  "color": "",
  "height": 1,
  "sides": [
    "back"
  ]
}
```

<a id="scalar-schema-wallopening"></a>

### WallOpening

**Type:** `object`

Parametric wall opening (door/window/open/railing). Layout documents never use the legacy windows/door/doorPos trio.

- **`center` (required)**: `number`

  Center as a 0–1 fraction along the wall
- **`height` (required)**: `number`, exclusiveMinimum: `0`

  Opening height, meters
- **`id` (required)**: `string`, minLength: `1`

  op\_ + nanoid
- **`kind` (required)**: `string`, possible values: `"window", "door", "open", "railing"`
- **`side` (required)**: `string`, possible values: `"back", "front", "left", "right"`
- **`sill` (required)**: `number`, minimum: `0`

  Bottom edge above the floor, meters (0 for doors)
- **`width` (required)**: `number`, exclusiveMinimum: `0`

  Opening width, meters
- **`edge`**: `integer`, minimum: `-9007199254740991`, maximum: `9007199254740991`

  Traced-outline edge index for shaped rooms; absent = the 4-side address
- **`frameColor`**: `string`

  Casing/frame paint as #rrggbb; omitted = inherit
- **`hinge`**: `string`, possible values: `"start", "end"`

  Door hinge jamb; windows ignore it
- **`leaf`**: `string`, possible values: `"swing", "sliding", "bifold", "pocket"`

  Door leaf type; omitted = swing, which is never stored
- **`leafColor`**: `string`

  Door leaf paint as #rrggbb
- **`leafStyle`**: `string`, possible values: `"flush", "lite", "glass", "panel", "twoPanel"`

  Door leaf face; omitted = flush, which is never stored
- **`open`**: `boolean`

  Door leaf open; only false is stored
- **`panes`**: `integer`, minimum: `0`, maximum: `9007199254740991`

  Window panes: omitted/0 = auto, 1 = single sheet, N = N panes. Doors: 0 = no leaf (cased opening)
- **`swing`**: `string`, possible values: `"in", "out"`

  Door swing; only "out" is stored

<a id="scalar-example-117"></a>

**Generated example:**

```json
{
  "center": 1,
  "edge": -9007199254740991,
  "frameColor": "",
  "height": 1,
  "hinge": "start",
  "id": "",
  "kind": "window",
  "leaf": "swing",
  "leafColor": "",
  "leafStyle": "flush",
  "open": true,
  "panes": 0,
  "side": "back",
  "sill": 0,
  "swing": "in",
  "width": 1
}
```

<a id="scalar-schema-walltrim"></a>

### WallTrim

**Type:** `object`

Mouldings along a room's walls, one key per kind of trim. Beta.

- **`baseboard`**: `object`

  A moulded baseboard in place of the plain painted skirting
  - **`style` (required)**: `string`, possible values: `"classic", "tall"`

    The board's look, smallest first
  - **`color`**: `string`

    Board paint; absent means the wall paint, a shade lighter, as #rrggbb
- **`chair`**: `object`

  A chair rail partway up every wall, broken at doors and windows
  - **`height` (required)**: `number`

    Top of the rail above the floor, meters
  - **`color`**: `string`

    Rail paint; absent means the wall paint, a shade lighter, as #rrggbb
- **`crown`**: `object`

  The moulding where the walls meet the ceiling, on every wall
  - **`style` (required)**: `string`, possible values: `"simple", "classic", "grand"`

    The moulding's look, smallest first
  - **`color`**: `string`

    Moulding paint; absent means the wall paint, a shade lighter, as #rrggbb
- **`picture`**: `object`

  A picture rail a little below the ceiling, on every wall
  - **`drop` (required)**: `number`

    How far the rail's top sits below the wall top, meters
  - **`color`**: `string`

    Rail paint; absent means the wall paint, a shade lighter, as #rrggbb

<a id="scalar-example-118"></a>

**Generated example:**

```json
{
  "baseboard": {
    "color": "",
    "style": "classic"
  },
  "chair": {
    "color": "",
    "height": 1
  },
  "crown": {
    "color": "",
    "style": "simple"
  },
  "picture": {
    "color": "",
    "drop": 1
  }
}
```
