# I'mBoard API Documentation

> Agent-first documentation for the I'mBoard REST API.

## Machine-readable endpoints

- [/openapi.json](/openapi.json): OpenAPI 3.1 specification
- [/api/ontology/index.json](/api/ontology/index.json): Board Ontology — full catalog (143 KPIs across 7 domains, tier-labeled). Versioned envelope { version, releasedAt, kpis }; immutable snapshots at /api/ontology/v/<version>/index.json. Selected KPIs carry an optional `calculationPolicy` block (inclusion / exclusion / required inputs / edge cases / validation checks / common miscomputations) — the agent-safe execution contract for computing the metric from a company's data. Numeric KPIs also carry an optional `metricBasis` block: enum axes (timeBasis, moneyBasis, cohortBasis, dateBasis, production) you can filter the catalog on deterministically.
- [/api/ontology/schema.json](/api/ontology/schema.json): JSON Schema for the Board Ontology responses. Validate /api/ontology/index.json against #/definitions/OntologyResponse, /api/ontology/{domain}.json against #/definitions/OntologyDomainResponse, /api/ontology/{domain}/{slug}.json against #/definitions/OntologyKpiResponse.
- [/api/schema-index/index.json](/api/schema-index/index.json): Resource JSON schemas
- [/api/recipe-index/index.json](/api/recipe-index/index.json): Dossier recipes

## Documentation pages

- [I'mBoard API Documentation](/docs): Agent-first documentation for the I'mBoard REST API. Schemas, recipes, and guides for AI agents and developers.
- [API Reference](/docs/api-reference): Interactive API reference generated from the I'mBoard OpenAPI 3.1 specification.
- [Authentication](/docs/getting-started/authentication): All API requests require a valid token in the Authorization header.
- [Conventions](/docs/getting-started/conventions): Standard patterns that apply across all API endpoints.
- [Errors](/docs/getting-started/errors): All errors follow a consistent envelope format with machine-readable codes.
- [Known V1 Limitations](/docs/getting-started/known-limitations): V1 is an intentionally scoped first release. This documents what V1 does not include and why.
- [Pagination, Filtering & Sorting](/docs/getting-started/pagination-filtering-sorting): Collection endpoints support cursor-based pagination, field sorting, and query filtering.
- [Quickstart](/docs/getting-started/quickstart): Get your first successful API call in under 2 minutes.
- [Versioning & Breaking Changes](/docs/getting-started/versioning): How I'mBoard versions its public API and communicates breaking changes.
- [MCP — install & tool reference](/docs/guides/claude-code-and-mcp): Install the I'mBoard MCP server in Claude Code, Claude Desktop, Cursor, Cline, and other MCP-aware clients. Includes the full live tool catalog.
- [Guide: CLI](/docs/guides/cli): Use the imboard CLI to manage boards, meetings, documents, and reports from your terminal.
- [Guide: Create & Update a Meeting](/docs/guides/create-update-meeting): How to create a new meeting and update its details via the API.
- [Guide: First API Call](/docs/guides/first-api-call): A detailed walkthrough for making your first authenticated API call.
- [Guide: List Board Meetings](/docs/guides/list-board-meetings): How to paginate through a board's meetings using cursor-based pagination.
- [Knowledge Base](/docs/kb): Learn how to use I'mBoard to run your board meetings, manage documents, and keep stakeholders informed.
- [Changelog](/docs/ontology/changelog): Every Board Ontology release — added, removed, promoted, and changed KPIs. Pin to a specific version using the immutable snapshots at /api/ontology/v/<version>/.
- [Board Ontology](/docs/ontology): Meet Rogue, the I'mBoard Board Ontology — 148 KPIs in the catalog, 27 anchored to third-party standards, all tier-labeled, versioned, citable, open JSON, free MCP for any AI assistant.
- [Methodology](/docs/ontology/methodology): Why every I'mBoard Board Ontology KPI cites its source — industry-backed vs I'mBoard-authored tiers, the versioned envelope, SMSB attribution requirements, definition lifecycle, and how disputes are handled.
- [Recipes](/docs/recipes): Pre-built, machine-readable YAML recipes that orchestrate common I'mBoard agent workflows — financial updates, pipeline syncs, and investor updates.
- [Monthly Investor Update](/docs/recipes/investor-update): Recipe for a founder's AI agent to draft and send a structured monthly investor update via the I'mBoard API — no manual drafting in the UI.
- [Boards](/docs/resources/boards): A board represents a governance board in I'mBoard. List and retrieve boards.
- [Dashboards](/docs/resources/dashboards): Dashboard configurations nested under reports.
- [Documents](/docs/resources/documents): Board document metadata. V1 returns metadata only — no file download.
- [Me](/docs/resources/me): Retrieve the authenticated user's profile. The simplest way to verify your token.
- [Meetings](/docs/resources/meetings): Board meeting scheduling, location, and lifecycle management.
- [Members](/docs/resources/members): Board membership, roles, access levels, and board positions.
- [Reports](/docs/resources/reports): Board report generation and retrieval. Reports contain dashboards.
- [Manage Your Subscription](/docs/kb/billing/manage-subscription): Understand I'mBoard's pricing, trial period, seat management, and billing lifecycle.
- [Share Documents](/docs/kb/documents/share-documents): Understand who can access board documents and how to share them.
- [Upload & Organize Documents](/docs/kb/documents/upload-and-organize): Add files and links to your board's document library, categorize them, and track versions.
- [Create Your Board](/docs/kb/getting-started/create-your-board): Set up your first I'mBoard workspace in under a minute.
- [Invite Members](/docs/kb/getting-started/invite-members): Add board members, assign roles and positions, and manage access to your board.
- [Schedule a Meeting](/docs/kb/meetings/schedule-a-meeting): Propose meeting times, collect votes from attendees, and confirm your next board meeting.
- [Create a Report](/docs/kb/reports/create-a-report): Build board reports with dashboards, assign owners, and manage the review-to-publish workflow.
- [Gross Revenue Retention (GRR)](/docs/ontology/customers/gross_revenue_retention): Recurring revenue retained from the cohort of customers present at the start of the period, excluding expansion — so the metric captures only churn and contraction. Per the SaaS Metrics Standards Board (SMSB) GRR standard. GRR is bounded at 100% (cannot exceed it) and reads as the "no-defense-against-churn" floor on retention. The board reads GRR alongside NRR (`customers.net_revenue_retention`) — the gap between them is the expansion contribution. Common pitfall: treating GRR and NRR as substitutes — they answer fundamentally different questions, and a healthy NRR with sliding GRR signals churn masked by upsell. — Customers KPI anchored to SaaS Metrics Standards Board.
- [Customers KPIs](/docs/ontology/customers): Retention, health, NPS, concentration. 16 KPIs in this domain — 5 anchored to third-party standards, 11 editorial.
- [Logo Churn Rate](/docs/ontology/customers/logo_churn_rate): Share of customer logos lost during the period — the inverse of logo retention. Numerator is logos that churned during the period; denominator is logos present at period start. Per the KBCM/Sapphire Private SaaS Company Survey definition (treated as the de-facto private-SaaS reporting convention). The board reads this as the simplest churn signal — independent of revenue-weighting. Common pitfall: confusing annualized vs. period-rate (monthly churn × 12 ≠ annualized churn for a compounding base) — be explicit about the time window and annualization method. — Customers KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [Logo Retention Rate](/docs/ontology/customers/logo_retention_rate): Share of customer logos retained from the prior period, counted by logo (not by revenue). Per the SaaS Metrics Standards Board (SMSB) Logo Retention standard: numerator is logos present at both period start and period end; denominator is logos present at period start. New logos acquired during the period are excluded from both. The board reads this as a "stickiness" signal independent of ACV: high logo retention with weak NRR points to flat/contracting expansion; weak logo retention with strong NRR points to high concentration risk. Common pitfall: conflating logo retention with revenue retention — they answer different questions and routinely diverge. — Customers KPI anchored to SaaS Metrics Standards Board.
- [Net Revenue Retention (NRR)](/docs/ontology/customers/net_revenue_retention): Recurring revenue retained from the cohort of customers present at the start of the period, including expansion (upsell, cross-sell, price increases) and net of churn and contraction — but excluding revenue from net-new logos acquired in-period. Per the SaaS Metrics Standards Board (SMSB) NRR standard. NRR above 100% means the cohort grew faster than it lost — a hallmark of strong product-led expansion. The board reads NRR alongside GRR (`customers.gross_revenue_retention`) to separate the "keep + expand" signal from the "just keep" signal. Common pitfall: mixing GAAP revenue and ARR in numerator vs. denominator, or letting net-new logo revenue leak in — both inflate the number; SMSB is explicit that the cohort is closed at period start. — Customers KPI anchored to SaaS Metrics Standards Board.
- [NPS Score](/docs/ontology/customers/nps_score): Net Promoter Score — % of survey respondents who are promoters (score 9–10) minus % detractors (0–6), passives (7–8) excluded. Per the original NPS methodology (Reichheld, Bain & Company, 2003). The score ranges from −100 to +100. The board reads NPS as one read on product-market fit and word-of-mouth potential, not as a precise customer-loyalty measurement — the methodology is well-known for being sensitive to sample bias, response rate, and survey timing. Common pitfall: comparing NPS across companies without normalizing for industry — B2B SaaS NPS distributions sit much higher than consumer-app NPS, and the absolute number means little without a peer cohort. — Customers KPI anchored to Retently NPS Benchmarks 2025.
- [Finance KPIs](/docs/ontology/finance): Cash, revenue, burn, runway, expenses. 19 KPIs in this domain — 1 anchored to third-party standards, 18 editorial.
- [Runway (Months)](/docs/ontology/finance/runway_months): Estimated number of months the company can operate at the current net burn before unrestricted cash reaches zero, holding everything else constant. The single most consequential survival input for venture-backed companies — it sets the urgency of every fundraising, hiring, and cost decision. Common pitfall: runway is often quoted off `finance.total_cash_in_bank` and a single-month spot-burn instead of operationally-available cash and a 3-month-trailing burn — the result is a runway that looks 2–4 months longer than it actually is when working capital tightens. Boards should ask which cash and which burn went into the calculation. — Finance KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [Outstanding Convertible Amount](/docs/ontology/fundraising/convertible_outstanding): Total principal value of SAFEs and convertible notes outstanding that have not yet converted to equity. These convert at the next priced round, typically at a discount or valuation cap (per the standard Y Combinator SAFE templates and the National Venture Capital Association convertible-note model). Common pitfall: a SAFE stack quietly accumulating between rounds can convert into 15–25% dilution at the next priced round, surprising founders who modeled "we only sold 10% in this priced round" math. Boards should always see the fully-diluted cap table including SAFE conversion. — Fundraising KPI anchored to Y Combinator Post-Money SAFE (2018+ standard form).
- [Founder Dilution](/docs/ontology/fundraising/founder_dilution): Percentage of founders' fully-diluted ownership that is given up in the new round, including any pre-close option-pool top-up (the "option pool shuffle" — option-pool expansion taken in the pre-money dilutes existing holders rather than new investors). Common pitfall: founders often quote the "investor dilution" (new money / post-money) and forget the option-pool top-up component. The Carta State of Private Markets quarterly reports publish stage-typical dilution ranges that boards should use as a sanity check. — Fundraising KPI anchored to Carta State of Private Markets Q3 2025.
- [Fundraising KPIs](/docs/ontology/fundraising): Round status, investor pipeline, cap table. 23 KPIs in this domain — 5 anchored to third-party standards, 18 editorial.
- [Post-Money Valuation](/docs/ontology/fundraising/post_money_valuation): Company valuation immediately after the new round closes, including the new capital raised — the canonical "valuation" number quoted in TechCrunch headlines. Per NVCA Model Documents, post-money = pre-money + new money raised. Common pitfall: post-money math gets messy with SAFEs — modern post-money SAFEs (the YC 2018+ form, per the Y Combinator SAFE primer) fix dilution at the SAFE's valuation cap regardless of subsequent priced-round pricing, so the board should always reconcile the headline post-money against the fully-diluted cap table. — Fundraising KPI anchored to NVCA Model Legal Documents (2024 revision).
- [Pre-Money Valuation](/docs/ontology/fundraising/pre_money_valuation): Company valuation negotiated with investors immediately before the new round closes — the denominator for the new investors' ownership math. Per the NVCA Model Documents, pre-money = post-money − new money raised. Common pitfall: when convertible instruments (SAFEs, notes) are outstanding, the "headline" pre-money the CEO quotes and the effective pre-money after conversion can differ materially — the board should always ask for both. Equally important: option-pool top-ups taken pre-close come out of the pre-money share count, diluting founders not investors (the "option pool shuffle"). — Fundraising KPI anchored to NVCA Model Legal Documents (2024 revision).
- [Total Round Size](/docs/ontology/fundraising/total_round_size): Total new capital being raised in the current round across all participants — the lead, follow-on investors, employee/strategic allocations, and any side-letter pieces. This is the figure that goes into the post-money math. Common pitfall: companies sometimes confuse `total_round_size` with `target_raise` — the round size is final and used in valuation math, while the target is what management is aiming for and can move during the raise. Boards should expect a specific breakdown by investor when this number is reported. — Fundraising KPI anchored to NVCA Model Legal Documents (2024 revision).
- [ARR per FTE](/docs/ontology/hr/arr_per_fte): Annual Recurring Revenue divided by total FTE-equivalent workforce — the canonical SaaS workforce-productivity ratio anchored to the SaaS Capital Annual Survey methodology (revenue per employee benchmarks). A high-signal denominator for "are we over- or under-staffed for our revenue scale?" Common pitfall: choosing different ARR conventions (ending vs average, GAAP-reconciled vs raw) without locking in a board-level standard. Best practice is to pair this with `sales.arr` so the numerator is unambiguous and to disclose whether contractors are included in the FTE denominator. — HR KPI anchored to SaaS Capital Annual Survey 2025 (14th Annual).
- [Average Days to Fill](/docs/ontology/hr/avg_days_to_fill): Mean elapsed days between requisition opening (approved and posted) and offer acceptance, averaged across requisitions filled in the period. The headline recruiting-velocity KPI commonly tracked in the SHRM Talent Acquisition Benchmarking Report. Common pitfall: choosing between time-to-fill (req-opened to offer-accepted) and time-to-hire (first-applicant to offer-accepted) without locking the convention — the two can differ by weeks. Best practice is to standardize on time-to-fill (the SHRM benchmark convention) and document any deviation. — HR KPI anchored to SHRM Talent Acquisition Benchmarking Report.
- [HR KPIs](/docs/ontology/hr): Headcount, hiring, attrition, compensation. 28 KPIs in this domain — 4 anchored to third-party standards, 24 editorial.
- [Involuntary Turnover Rate](/docs/ontology/hr/involuntary_turnover_rate): Annualized rate of company-initiated separations as a percentage of average headcount. Complement to `hr.voluntary_turnover_rate`; together they form the total turnover picture per the Mercer US Turnover Survey methodology. Common pitfall: lumping one-time RIFs into the steady-state rate, which makes the trend unreadable. Best practice is to report steady-state involuntary turnover and call out any RIF events separately in `hr.board_actions` with the headcount delta. — HR KPI anchored to Mercer US Turnover Survey 2025.
- [Voluntary Turnover Rate](/docs/ontology/hr/voluntary_turnover_rate): Voluntary exits over a trailing period, expressed as an annualized percentage of average headcount — the headline attrition number on the HR scorecard. Anchored to the Mercer US Turnover Survey methodology (Mercer reports voluntary vs involuntary turnover annually). Common pitfall: comparing a single quarter's annualized rate against an annual benchmark — short-window annualization is noisy. Best practice is trailing-12-months for benchmark comparison and trailing-3 or trailing-6 for trend reads. Per #1426: stage-specific industry norms here are folk-wisdom unless tied to a specific Mercer or comparable published cut. — HR KPI anchored to Mercer US Turnover Survey 2025.
- [Operations KPIs](/docs/ontology/operations): Cross-functional operational metrics. 1 KPI in this domain — 1 anchored to third-party standards.
- [Rule of 40](/docs/ontology/operations/rule_of_40): Composite SaaS health score that sums the company's revenue growth rate and a profitability proxy (commonly EBITDA margin or free-cash-flow margin) into a single percentage. Originally articulated by Brad Feld in 2015 and codified by the SaaS Metrics Standards Board, the rule frames the growth-vs-profitability tradeoff: a company growing at 60% with a −20% margin scores 40, equal to a company growing at 20% with a +20% margin. The board reads it to sanity-check whether growth is being bought at unhealthy burn or whether margin discipline is constraining growth too far. Common pitfall: which profitability proxy is used materially changes the score (FCF margin is the strictest, EBITDA more flattering, "operating margin" inconsistently defined), so pick one and disclose it next to the number. — Operations KPI anchored to SaaS Metrics Standards Board.
- [Product KPIs](/docs/ontology/product): Roadmap, delivery, R&D efficiency, quality. 16 KPIs in this domain — 1 anchored to third-party standards, 15 editorial.
- [R&D Monthly Spend](/docs/ontology/product/rd_monthly_spend): Total monthly cash outflow on research and development — fully-loaded engineering, product, and design payroll plus tooling, infrastructure dedicated to product development, contractors, and direct R&D vendor spend. The "input" side of R&D efficiency. Common pitfall: companies report base-payroll R&D and exclude the loaded cost (benefits, stock comp at cash-cost basis, allocated rent, dev tooling), under-reporting true R&D burn by 25–40%. Boards should always ask whether the number is base-payroll, fully-loaded, or GAAP R&D expense — they tell different stories. The KBCM/Sapphire SaaS Survey reports R&D as a percentage of revenue for its company panel — use that as the benchmarking lens. — Product KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [ARR](/docs/ontology/sales/arr): Annual Recurring Revenue — the value of all recurring subscription revenue normalized to a one-year run-rate as of the period close. The headline operating metric for a subscription business; every growth and efficiency ratio (NRR, GRR, magic number, CAC payback, Rule of 40) is calibrated against it. Excludes one-time fees, professional services, and non-contractual usage. Common pitfall: confusing ARR (contracted recurring) with revenue (recognized) or with CARR (contracted incl. not-yet-live) — the SMSB standard draws sharp lines between them, and boards expect the same discipline. The KpiVarianceTable widget surfaces forecast / actual / variance / status / future-forecast columns against the same field. — Sales KPI anchored to SaaS Metrics Standards Board.
- [Average Contract Value](/docs/ontology/sales/avg_contract_value): Average annualized contract value across new-customer deals signed during the period (ACV). Defines where the company plays on the SaaS deal-size spectrum and dictates the operating model — high-ACV businesses tolerate longer sales cycles and direct sales motions; low-ACV businesses must run product-led or inside-sales motions to keep CAC payback short. Common pitfall: blending new and expansion ACV obscures the new-logo deal-size trend that boards actually want to see. Anchored to KBCM/Sapphire SaaS Survey 2024 §Average Contract Value for cross-company benchmarking. — Sales KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [Blended CAC Ratio](/docs/ontology/sales/blended_cac_ratio): Total fully-loaded S&M spend in the period divided by the dollars of new CARR generated in the period (new-customer + expansion CARR combined). Per the SMSB standard, the headline efficiency ratio for the full sales-and-marketing motion — answers "how many cents do we spend on S&M to add one dollar of contracted ARR." Common pitfall: blending without separately reporting New CAC Ratio and Expansion CAC Ratio hides which side of the motion is driving efficiency — for a healthy SaaS company expansion CAC is usually 3–5× cheaper per dollar than new-logo CAC. — Sales KPI anchored to SaaS Metrics Standards Board.
- [Customer Acquisition Cost](/docs/ontology/sales/cac): Fully-loaded sales-and-marketing (S&M) expense incurred to acquire one new customer during the period. Per the SMSB standard, the CAC numerator includes salaries + commissions + benefits + travel + marketing programs + tooling — i.e. all S&M costs, not just direct-attribution paid acquisition. The denominator is new logos, not deals. Common pitfall: omitting fully-loaded comp (especially BDR/SDR base salary and CS-team cost-of-sale where they participate in expansion) understates CAC and inflates every downstream efficiency metric. The board cares about CAC alongside CAC Payback and the CAC Ratio family — single-number CAC is a building block, not a verdict. — Sales KPI anchored to SaaS Metrics Standards Board.
- [CAC Payback Period](/docs/ontology/sales/cac_payback_period): Number of months required for the gross profit generated from a new customer's ARR to recover the fully-loaded S&M spend used to acquire them. The single most decision-useful efficiency metric at the board level — it directly connects acquisition cost, ACV, and gross margin into one "how long until we break even on this customer" answer. Per the SMSB standard, the calculation must use gross-margin-adjusted ARR in the denominator (not raw ARR) to be cross-company comparable. Common pitfall: using raw ARR understates payback by ~25–30 percentage points and breaks comparability with peer benchmarks. — Sales KPI anchored to SaaS Metrics Standards Board.
- [CARR](/docs/ontology/sales/carr): Contracted Annual Recurring Revenue — recognized MRR × 12 plus the annualized value of contracts that are signed but not yet live (i.e. implementation, ramp, deferred-start). Per the SMSB standard, CARR sits between ARR (live only) and pipeline (unsigned) on the revenue-certainty spectrum: contractually committed but not yet delivered. Boards reading CARR > ARR gap can quantify the in-flight implementation backlog and the leading indicator of next-period ARR. Common pitfall: counting verbal commitments or LOIs as CARR — only signed contracts qualify under the SMSB definition. — Sales KPI anchored to SaaS Metrics Standards Board.
- [Expansion CAC Ratio](/docs/ontology/sales/expansion_cac_ratio): Fully-loaded S&M plus Customer Success expense attributable to expansion divided by expansion CARR generated in the period. Per SMSB, the efficiency read on the upsell / cross-sell / land-and-expand motion. Distinct from the new-logo CAC ratio because the cost base often includes CSMs whose primary metric is retention but whose secondary metric is expansion — boards expect to see that allocation called out. Common pitfall: excluding CS comp entirely understates the true cost of expansion; including all of CS overstates it. The SMSB standard prescribes a documented allocation rule (typically tied to expansion-quota OTE share). — Sales KPI anchored to SaaS Metrics Standards Board.
- [Gross Margin](/docs/ontology/sales/gross_margin): Recognized revenue minus cost of goods sold (COGS), divided by recognized revenue, expressed as a percentage. The single best read on whether the business model can ever generate operating leverage — a low gross margin caps every downstream efficiency metric (CAC payback, LTV/CAC, Rule of 40). For SaaS, COGS includes hosting, third-party software, customer support, and customer-success cost-of-service. Common pitfall: omitting customer success from COGS inflates the margin and breaks comparability with peer benchmarks. Anchored to KBCM/Sapphire SaaS Survey 2024 §Gross Margin. — Sales KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [Growth Rate (YoY)](/docs/ontology/sales/growth_rate_yoy): Year-over-year percentage growth in ARR (or recognized revenue, if explicitly anchored) — comparing the current period to the equivalent period 12 months prior. The single most-watched investor metric and the largest single driver of SaaS valuation multiples. Common pitfall: comparing to the prior quarter (QoQ) and reporting it as "growth rate" — boards and investors mean YoY unless explicitly noted otherwise. Anchored to KBCM/Sapphire SaaS Survey 2024 §YoY ARR Growth for cross-company benchmarking. — Sales KPI anchored to KBCM/Sapphire SaaS Survey 2024 (15th Annual).
- [Sales KPIs](/docs/ontology/sales): ARR, bookings, pipeline, deals, forecast. 45 KPIs in this domain — 10 anchored to third-party standards, 35 editorial.
- [New CAC Ratio](/docs/ontology/sales/new_cac_ratio): S&M expense attributable to new-customer acquisition divided by the new-customer CARR generated in the period. Per SMSB, the cleanest read on the new-logo acquisition engine's efficiency — strips out the expansion motion which has materially different unit economics. Common pitfall: failing to split AE comp time correctly between new and expansion activities — when the same AE owns both motions, an allocation rule (often the % of OTE tied to new-vs-expansion quota) is required and must be applied consistently quarter-over-quarter. — Sales KPI anchored to SaaS Metrics Standards Board.