Application API reference

Navigate the financial-review endpoints and their concurrency, company and approval contracts.

Browse documentation

On this page

These are application endpoints, not endpoints on the documentation website. They support the current web application and are not a separately versioned public integration API. Consult the route and contract files in your installed application revision before building automation.

Authentication and company context

Requests use the installation’s configured authentication. Protected routes resolve the current identity and company membership. There is no general API-key integration mechanism documented here.

Financial-review POST requests require x-company-id to match the active company. Supplying the header does not grant access to that company. Browser mutations also enforce request-origin controls.

Read surfaces

Endpoint	Purpose
`GET /api/financial-progress`	Goal progress, guided readiness, weekly cash and recognition review
`GET /api/financial-progress?month=YYYY-MM&preview=TOKEN`	Inspect a month against the current outlook preview
`GET /api/goal-review`	Goal versions, evaluations, preferences and recent snapshots
`GET /api/goal-review/outlook?preview=TOKEN`	Current pinned calculation inputs and lineage
`GET /api/goal-review/bridge?baseline=UUID&preview=TOKEN`	Explanation against a compatible preserved baseline
`GET /api/goal-review/snapshots/UUID`	A complete preserved goal snapshot
`GET /api/forecast-reconciliation`	Candidates, obligations, allocations, recurrence, coverage and recovery
`GET /api/goal-decisions`	Scenario, plan and saved-decision choices
`GET /api/goal-decisions?id=UUID`	Preserved decision evaluation, approval or outcome
`GET /api/import-review`	Import sources and saved reviews
`GET /api/import-review?id=UUID`	One preserved import review
`GET /api/financial-reviews`	Work reviews, members, baselines, scenarios and expectation choices
`GET /api/financial-reviews?id=UUID`	Report, tasks, sign-off history and stale status

Command families

All commands below use POST to the matching resource.

Resource	Actions
`/api/goal-review`	`create_goal`, `revise_goal`, `set_primary_goal`, `save_snapshot`
`/api/forecast-reconciliation`	`capture`, `allocate`, `revoke_allocation`, `revise_occurrence`, `coverage`, `approve_history`, `approve_recurrence`, `pause_recurrence`, `preview_recurrence_replacement`, `replace_recurrence`
`/api/goal-decisions`	`preview`, `save_evaluation`, `approve`, `preview_outcome`, `save_outcome`
`/api/import-review`	`preview`, `save_evaluation`, `approve`
`/api/financial-reviews`	`preview`, `create`, `assign_reviewer`, `task`, `submit`, `refresh`, `sign`
`/api/financial-progress`	`map_cash_account`, `draft_driver_change`, `preview_recognition`, `link_recognition`, `unlink_recognition`

For example, a current financial report preview has this body:

{"action":"preview","scope":{"kind":"cycle"}}

Use the returned report and token to populate the reviewed save request. Do not invent a preview token, expected version, baseline ID or source hash.

Concurrency and retries

A preview token or definition hash pins the source state being approved. Changed inputs require a new preview.
Expected versions prevent stale edits. Reload and reconcile intent after a conflict.
Commands with requestKey require a UUID. Retry the same intent with the same key; do not reuse it for changed content.
Ownership and approval checks still apply even if an identifier or token is valid.

Minor-unit financial amounts are decimal integer strings in the relevant contracts. Display amounts and formula inputs may use major units, so do not assume a field’s units from its name alone. Dates use ISO calendar dates and months use YYYY-MM; the current-outlook cutoff is UTC.

Errors and contracts

Typical responses include 400 for invalid requests, 403 for authority failures, 404 for unavailable scoped records, 409 for stale versions or previews, 413 for request size limits, and 422 for unsupported or blocked financial actions. Missing review schema returns a migration instruction rather than silently disabling the feature.

The contract sources are apps/web/src/lib/goal-review-contract.ts, forecast-reconciliation-contract.ts, goal-decisions-contract.ts, import-review.ts, financial-progress.ts, and financial-reviews.ts. Size limits and action-specific fields are enforced there and in the route handlers.

Health and scheduled-job bearer credentials are separate operational secrets; they do not grant access to these user-facing financial APIs. See Operating an installation.