Room

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/hummingdeck/main/json-schema/hummingdeck-room-schema.json",
  "title": "Room",
  "x-generated": "2026-10-24",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hummingdeck-openapi.json#/components/schemas/Room",
  "type": "object",
  "properties": {
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RoomLabelRef"
      }
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ]
    },
    "welcomeMessage": {
      "type": [
        "string",
        "null"
      ]
    },
    "allowDownloads": {
      "type": "boolean"
    },
    "viewerLayoutMode": {
      "type": "string",
      "enum": [
        "viewer-choice",
        "list",
        "grid"
      ]
    },
    "viewerThemeMode": {
      "type": "string",
      "enum": [
        "light",
        "system",
        "viewer-choice"
      ]
    },
    "sender": {
      "type": "object",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "format": "email"
        }
      },
      "required": [
        "name",
        "title",
        "email"
      ]
    },
    "company": {
      "oneOf": [
        {
          "$ref": "#/$defs/RoomCompanyReference"
        },
        {
          "type": "null"
        }
      ],
      "description": "Returned only when the API key has crm:read; otherwise null."
    },
    "contact": {
      "oneOf": [
        {
          "$ref": "#/$defs/RoomContactReference"
        },
        {
          "type": "null"
        }
      ],
      "description": "Returned only when the API key has crm:read; otherwise null."
    },
    "tabs": {
      "type": "array",
      "description": "In the room's tab order.",
      "items": {
        "$ref": "#/$defs/RoomTab"
      }
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RoomItem"
      },
      "description": "Tab by tab, in tab order, then in order within each tab."
    },
    "links": {
      "type": "object",
      "properties": {
        "active": {
          "type": "integer",
          "minimum": 0
        },
        "total": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "active",
        "total"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "name",
    "status",
    "welcomeMessage",
    "allowDownloads",
    "viewerLayoutMode",
    "viewerThemeMode",
    "sender",
    "company",
    "contact",
    "tabs",
    "items",
    "links",
    "createdAt",
    "updatedAt",
    "labels"
  ],
  "$defs": {
    "RoomCompanyReference": {
      "type": "object",
      "description": "The company fields embedded in a room or room-link response.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "domain": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "domain"
      ],
      "additionalProperties": false
    },
    "RoomContactReference": {
      "type": "object",
      "description": "The contact fields embedded in a room or room-link response.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "format": "email"
        }
      },
      "required": [
        "id",
        "firstName",
        "lastName",
        "email"
      ],
      "additionalProperties": false
    },
    "RoomItem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "tabId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "The tab the item appears in. Items stored without a tab appear in the first content tab and report that tab."
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "0-based place within its tab."
        },
        "type": {
          "type": "string",
          "enum": [
            "document",
            "url",
            "embed",
            "section"
          ]
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "documentId": {
          "type": [
            "string",
            "null"
          ]
        },
        "processingStatus": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "pending",
            "processing",
            "completed",
            "failed",
            null
          ],
          "description": "Documents only; null for other items. A document can be added while it is still processing; send the room link once it reads completed."
        },
        "processingErrorCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why processing failed, when processingStatus is failed."
        },
        "deliveryMode": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "preview",
            "download_only",
            null
          ],
          "description": "Documents only; null for other items. download_only files are never previewed: recipients download them and open them on their device, and their downloads stay on for every link."
        },
        "urlId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "embedUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "allowDownloads": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "tabId",
        "position",
        "type",
        "title",
        "documentId",
        "processingStatus",
        "processingErrorCode",
        "deliveryMode",
        "urlId",
        "url",
        "embedUrl",
        "allowDownloads",
        "createdAt"
      ]
    },
    "RoomLabelRef": {
      "type": "object",
      "description": "A label as it appears on a room; the full record is at /room-labels.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "color": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "color"
      ]
    },
    "RoomTab": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "label": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "content",
            "action_items"
          ],
          "description": "content tabs hold items; the action_items tab shows the room's action plan."
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "0-based place in the room's tab order."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "label",
        "type",
        "position",
        "createdAt"
      ]
    }
  }
}