Skip to content

Workbook Models

This page documents the data models related to workbooks, sheets, and cell data.

Workbook

Represents an uploaded Excel file with its metadata and sheets.

Properties

Property Type Description
id string (UUID) Unique workbook identifier
name string Workbook display name
description string? Optional description
file_name string Original uploaded filename
file_size integer File size in bytes
sheet_count integer Number of sheets
status WorkbookStatus Current processing status
sheets Sheet[]? Array of sheet metadata (when requested)
stats WorkbookStats? Usage statistics (when requested)
created_by string Email of user who uploaded
created_at string (ISO 8601) Creation timestamp
updated_at string (ISO 8601) Last update timestamp

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CLO Portfolio Q1 2026",
  "description": "Quarterly portfolio snapshot",
  "file_name": "portfolio_q1_2026.xlsx",
  "file_size": 2458624,
  "sheet_count": 5,
  "status": "ready",
  "sheets": [
    {
      "name": "Holdings",
      "index": 0,
      "row_count": 150,
      "column_count": 45,
      "has_formulas": true,
      "formula_count": 450
    },
    {
      "name": "Summary",
      "index": 1,
      "row_count": 25,
      "column_count": 12,
      "has_formulas": true,
      "formula_count": 30
    }
  ],
  "stats": {
    "total_cells": 8250,
    "formula_cells": 480,
    "last_calculation": "2026-01-25T10:30:00Z",
    "calculation_count": 12
  },
  "created_by": "user@example.com",
  "created_at": "2026-01-25T09:00:00Z",
  "updated_at": "2026-01-25T10:30:00Z"
}

WorkbookStatus

Enumeration of possible workbook processing states.

Value Description
uploading File is being uploaded
processing File is being parsed and indexed
ready Workbook is ready for use
error Processing failed
recalculating Formulas are being recalculated

Status Transitions

uploading -> processing -> ready
                        -> error

ready -> recalculating -> ready
                       -> error

WorkbookStats

Statistics about workbook usage and content.

Properties

Property Type Description
total_cells integer Total number of cells with data
formula_cells integer Number of cells containing formulas
last_calculation string (ISO 8601)? Timestamp of last recalculation
calculation_count integer Number of times recalculated

Example

{
  "total_cells": 8250,
  "formula_cells": 480,
  "last_calculation": "2026-01-25T10:30:00Z",
  "calculation_count": 12
}

Sheet

Represents a single worksheet within a workbook.

Properties

Property Type Description
name string Sheet name
index integer Zero-based sheet index
row_count integer Number of rows with data
column_count integer Number of columns with data
has_formulas boolean Whether sheet contains formulas
formula_count integer Number of formula cells
headers string[]? First row column headers (when available)

Example

{
  "name": "Holdings",
  "index": 0,
  "row_count": 150,
  "column_count": 45,
  "has_formulas": true,
  "formula_count": 450,
  "headers": ["CUSIP", "Borrower", "Par", "Price", "Spread", "Rating"]
}

SheetData

Paginated data from a worksheet.

Properties

Property Type Description
sheet_name string Name of the sheet
columns ColumnInfo[] Column metadata
rows Row[] Array of row data
total_rows integer Total rows in sheet
page integer Current page number
page_size integer Rows per page
total_pages integer Total number of pages

Example

{
  "sheet_name": "Holdings",
  "columns": [
    {"name": "CUSIP", "type": "string", "index": 0},
    {"name": "Borrower", "type": "string", "index": 1},
    {"name": "Par", "type": "number", "index": 2},
    {"name": "Price", "type": "number", "index": 3},
    {"name": "Concentration", "type": "number", "index": 4, "has_formula": true}
  ],
  "rows": [
    {
      "_row_number": 2,
      "CUSIP": "ABC123DEF",
      "Borrower": "Acme Corp",
      "Par": 500000.00,
      "Price": 99.5,
      "Concentration": 2.5,
      "_formulas": {
        "Concentration": "=D2/SUM(D:D)*100"
      }
    }
  ],
  "total_rows": 150,
  "page": 1,
  "page_size": 50,
  "total_pages": 3
}

ColumnInfo

Metadata about a column in a sheet.

Properties

Property Type Description
name string Column header name
type CellType Detected data type
index integer Zero-based column index
has_formula boolean? Whether column contains formulas
excel_column string? Excel column letter (A, B, AA, etc.)

Example

{
  "name": "Par",
  "type": "number",
  "index": 2,
  "has_formula": false,
  "excel_column": "C"
}

Row

A single row of data from a sheet.

Properties

Property Type Description
_row_number integer Excel row number (1-indexed)
[column_name] any Column value (key is column name)
_formulas object? Formulas for cells (when requested)

Example

{
  "_row_number": 2,
  "CUSIP": "ABC123DEF",
  "Borrower": "Acme Corp",
  "Par": 500000.00,
  "Price": 99.5,
  "Rating": "Ba2",
  "Concentration": 2.5,
  "_formulas": {
    "Concentration": "=D2/SUM(D:D)*100"
  }
}

Cell

Represents a single cell value with optional formula.

Properties

Property Type Description
value any Cell value (string, number, boolean, null)
type CellType Value type
formula string? Formula string (if cell contains formula)
formatted_value string? Display-formatted value
error string? Error value if formula evaluation failed

Example

{
  "value": 2.5,
  "type": "number",
  "formula": "=D2/SUM(D:D)*100",
  "formatted_value": "2.50%",
  "error": null
}

CellType

Enumeration of cell value types.

Value Description JavaScript Type
string Text value string
number Numeric value number
boolean True/false value boolean
date Date or datetime string (ISO 8601)
error Excel error value string
empty Empty cell null

CellReference

Reference to a specific cell or range.

Properties

Property Type Description
sheet string? Sheet name (current sheet if omitted)
cell string Cell reference (A1, B2:D10, etc.)
absolute boolean Whether reference is absolute (\(A\)1)

Examples

// Single cell
{"cell": "A1"}

// Range
{"cell": "B2:D10"}

// Cross-sheet reference
{"sheet": "Summary", "cell": "B5"}

// Absolute reference
{"cell": "$A$1", "absolute": true}

WorkbookUploadRequest

Request body for workbook upload.

Properties

Property Type Required Description
file file Yes Excel file (multipart/form-data)
name string No Custom workbook name
description string No Workbook description

Constraints

Constraint Value
Max file size 100 MB
Max sheets 50
Max rows per sheet 1,000,000
Max columns per sheet 16,384
Supported formats .xlsx, .xls, .xlsm

WorkbookUpdateRequest

Request body for workbook update.

Properties

Property Type Required Description
name string No New workbook name
description string No New description

Example

{
  "name": "CLO Portfolio Q1 2026 (Updated)",
  "description": "Updated quarterly snapshot with corrections"
}