Comprehensive documentation for the Understory API's CompanyModel JSON structure. Use when working with Understory model JSON, parsing company model data, CompanyModel structure, Understory API response format, financial model JSON schema, extracting data from Understory models, Understory cell types, columnKey format, or boundingBox coordinates.
For authoritative schema definitions, refer to the OpenAPI specification. Key schemas:
| Schema | Location |
|---|---|
| CompanyModel | #/components/schemas/companyJsonModel |
| Cell values | #/components/schemas/cellValue |
| Source metadata | #/components/schemas/sourceMetadata |
| Period/Duration | #/components/schemas/period, #/components/schemas/duration |
| Rows | #/components/schemas/modelRow |
See openapi-reference.md for navigation guidance.
The Understory API generates structured JSON representations of financial models extracted from PDF documents. A CompanyModel contains stitched financial data from multiple uploaded files (10-Ks, 10-Qs, etc.), organized into hierarchical tables with full traceability back to source PDFs.
The primary data hierarchy flows:
tableGroups → tables → sections → rows → cells
Each cell contains:
value - The data value with type informationcolumnKey - DSL string identifying the time periodsourceMeta - Traceability back to the source PDF locationisForecast, isDeprecated, etc.)See data-model-hierarchy.md for structural overview.
Column keys use a pipe-delimited DSL format unique to Understory:
pr=FY-2023|ed=12/31/2023|dr=12-months
See column-key-dsl.md for field definitions, common patterns, and parsing implementations.
Cells can have these value types: dollar, number, percent, formula, string, multiple.
Key points:
#/components/schemas/cellValue for complete type definitionsSee openapi-reference.md for complete type definitions.
Every cell includes sourceMeta linking back to the source PDF with bounding box coordinates as ratios of page dimensions (0.0 to 1.0), not pixels.
See source-meta-and-geometry.md for coordinate conversion and highlighting utilities.
Models generated with summary configuration include a summary object with synthetic columns for common analysis periods (MRQ, LTM, etc.).
See summary-sheet.md for custom column definitions and structure.
Navigate tableGroups to find category: "Income Statement", then iterate rows.
See common-operations.py for get_income_statement_data().
Collect cells across a row, parse columnKey to order by date.
See common-operations.py for build_time_series().
Use sourceMeta.fileId and boundingBox to highlight source cells.
See source-meta-and-geometry.md.
Formula values contain recursive tree structures with operators and cell references. See openapi-reference.md for formula structure details.
Extract MRQ, LTM values from the summary sheet's custom columns. See summary-sheet.py.