Appearance

API Changelog ​

The Flowstate API follows Semantic Versioning. Breaking changes will only occur in major version bumps and will be announced well in advance.

For platform changes, see Flowstate Updates.

v1.4.0 — 2026-07-29 ​

R&D tax claims, AI spend tiering, autonomous cost-centre classification — and the cost centre returns to the project.

For platform changes, see Flowstate Updates.

Added ​

  • R&D tax claim surface. Queries: rdTaxClaims, rdTaxClaim(id), rdClaimWorkflow, rdJurisdictions, rdJurisdictionConfig, and calculateProjectCostForClaim. Lifecycle mutations: rdClaimCreate, createRdTaxClaim, updateRdTaxClaim, updateRdTaxClaimStatus, rdClaimAccept, and rdClaimDismiss. Cost mutations: addRdExpense, deleteRdExpense, and syncRdCostsFromApprovedAllocations. A claim carries a period (year + quarter), a jurisdiction, a framework, an editable deadline, and a per-claim cost split across employees, contractors and AI spend.
  • Eligibility scanning and project classification. analyzeProjectForRdQualification assesses a single project; upsertProjectClassification / deleteProjectClassification record the verdict. Scan cadence, enablement and lookback window are configured per organisation (RdScanConfig) — the lookback covers up to three prior fiscal years. Verdicts distinguish eligible, not eligible, and insufficient-context.
  • Rationale drafting and rewrite. rdClaimGenerateContent drafts the narrative sections; generateNarrativeQuestions / submitNarrativeAnswers run the targeted-question loop; rdClaimAnswerInterviewQuestion answers one inline. Selection rewrites are proposed as RationaleSuggestion rows and resolved with rdRationaleRewriteSelection, rdRationaleResolveSuggestion and rdRationaleResolveAllSuggestions. generateRdTaxDocumentation produces the submission pack.
  • AI spend export. A spreadsheet export covering the summary, the daily time series, Reported spend by provider / person / API key, and Attributed spend by project. Attributed cost fields are withheld server-side for organisations without the tier rather than hidden client-side.
  • Analysis-agent autonomy controls. AnalysisAgentConfig plus per-question AnalysisTypePolicy (off / suggest / auto_apply with a confidence threshold); runs and findings are recorded as AnalysisRun / AnalysisFinding. An auto-applied change carries its reason, confidence and model, and is revertible. Auto-apply only ever fills a null — it never overwrites a human-set value — and de-capitalising findings are always surfaced for review rather than applied. Enabling auto-apply requires the financial-configuration permission.
  • Post-completion cost centre on projects. LiveProject.completionCostCenterId (with its completionCostCentre relation) is readable and writable, and predicted by the analysis agent alongside the build centre.
  • Canonical workforce name. LiveEmployee.name (nullable) sits alongside firstName / lastName, backfilled for existing rows, with a shared display-name helper. This makes single-name records representable; email is genuinely optional.
  • New vacancy status value — committed. A LiveVacancy.status of committed sits between open and filled for an approved hire and contributes forecast cost exactly as an open vacancy does. status remains a free-form string; see src/lib/constants/vacancy-status.ts for the canonical set.
  • Ten new MCP/assistant tools. get_effort_gaps, get_uncosted_effort, get_submission_leaderboard, get_capex_declared_vs_claimed, get_capex_initiative_breakdown, get_capex_project_breakdown, list_rd_claims, list_forecast_budget_snapshots, get_forecast_budget_drift_summary, and mark_my_ai_sessions_as_project. See MCP server.
  • AI provider connection region. A provider connection carries a region, and that region's deployment performs the collection. Captured sessions are stamped with the geography they originated from instead of defaulting to Europe.

Changed ​

  • The cost centre resolves from the project, not the Initiative. This reverses the Initiative-first chain introduced in v1.3.0. resolveProjectCostCentre now returns the project's own costCentreId, falling back to the dormantCostCentreId stashed at adoption; the resolved source is always project. Initiative.costCentre is gone. capitalisable is derived from the category of the resolved cost centre (capex) and no longer from the Finance Mode. An Initiative's financeModeCapabilities.canCapitalise / canRdClaim are true when any child project's resolved centre is CapEx-category. See Initiative finance.
  • FinanceMode governs billing only. CLIENT_BILLING unlocks budgetedCost / budgetCurrency / marginPct; INTERNAL_COST hides them. Client billing no longer suppresses CapEx or R&D — the two are independent. Initiative.completionCostCentreId is unaffected.
  • Initiative money fields are roll-ups. effortActuals, forecast, aiSpend and varianceSummary sum the Initiative's child projects; committedFte and the AI budget remain the Initiative's own stated commitment. Initiative status is derived from its projects' delivery status rather than set directly.
  • Vacancy salary range collapsed to a single salary. LiveVacancy.salary is the one source of truth. The deprecated min/max range is still accepted on external contracts (REST and integration hooks) and migrated on write.
  • FTE is day-weighted. Assigned and actual FTE are now a day-weighted average over the requested window, so a mid-period joiner contributes a partial FTE and monthly, quarterly and annual reads reconcile.
  • Money converts at the current FX rate. Currency conversion uses the rate in force as of today rather than the oldest rate on file.
  • Effort is expressed as FTE. The vestigial hoursAllocated column is dropped; effort is a percentage of a working day. Submitted and approved weeks are immutable to automated recomputation.

Removed ​

  • Initiative.costCentre — an Initiative carries no cost centre of its own (see Changed above).
  • Initiative resourcing commitments and check-ins — the per-subject InitiativeCommitment write surface and the set_initiative_commitment MCP tool are removed. An Initiative's resourcing is the aggregate of its projects' allocations.
  • CAPEX_RD_CLAIM as a live FinanceMode — every row was data-migrated to INTERNAL_COST and the value is never written again. It remains in the enum only because Postgres enum values cannot be dropped safely; do not branch on it.
  • LiveEffort.hoursAllocated — see Changed above.

v1.3.0 — 2026-06-08 ​

Initiative as finance anchor — GraphQL surface, MCP tools, and four new webhook entities.

For platform changes, see Flowstate Updates.

Added ​

  • Initiative finance-anchor GraphQL API. The Initiative type now carries the finance/governance anchor: financeMode (CAPEX_RD_CLAIM / CLIENT_BILLING / INTERNAL_COST) + financeModeCapabilities, costCentre, budgetedCost/budgetCurrency, marginPct, committedFte, AI budget, lens, objective, the derived isInert / capitalisable flags, and the windowed rollups effortActuals, forecast, aiSpend, plannedCommitment, and varianceSummary. Money fields are gated behind FINANCIALS_VIEW_SUMMARY (zeroed without it).
  • Strategy + classification types. New Objective + KeyResult (the OKR layer above Initiatives), PortfolioLens (KTLO / Revenue / Cost-Reduction / Compliance), and InitiativeCommitment (planned per-subject committed FTE + AI budget). Queries: objectives, objective(id), portfolioLenses, capexClaims, capexClaim(id).
  • Finance + adoption mutations. initiativeFinanceUpdate (partial finance patch), initiativeAdoptProject / initiativeDetachProject (move a project's cost-centre anchor onto/off an Initiative; the project's own cost centre is stashed in dormantCostCentreId while adopted), and CRUD for objectives, key results, portfolio lenses, and commitments.
  • Pull-based CapEx/R&D claims. initiativeCapexClaimCreate (anchored — auto-pulls the Initiative's child projects as evidence; CAPEX_RD_CLAIM only), adHocCapexClaimCreate (hand-picked projects), and capexClaimConvertToInitiative. A one-claim-per-project-per-claimPeriodKey guard throws PROJECT_ALREADY_CLAIMED.
  • New error codes — PROJECT_ALREADY_ADOPTED, PROJECT_NOT_ADOPTED_HERE, CROSS_ORG_ADOPTION, and PROJECT_ALREADY_CLAIMED, each with deep-link ids in extensions. See API → Initiatives → Error codes.
  • Operating model — organizationOperatingModelUpdate(preset, terminology) relabels the workspace nouns (entityTerminology) and picks an operatingModelPreset; Organization now exposes both fields.
  • Four new webhook entity types — initiative, objective, portfolio_lens, and capex_claim now emit create / update / delete events. See Outbound Webhooks.
  • Six new MCP/assistant tools — read: search_initiatives, get_initiative_details, list_portfolio, list_objectives; live writes: add_initiative, update_initiative, adopt_project_to_initiative, detach_project_from_initiative, set_initiative_commitment, create_capex_claim. See MCP server.

Changed ​

  • A synced project is inert until anchored. A non-manual project with no cost centre and no Initiative carries no financial signal — it is excluded from capitalisation and the forecast until a human assigns a cost centre or adopts it into an Initiative. Finance reads resolve a project's cost centre and Finance Mode through the Initiative-first resolution chain. (Superseded in v1.4.0 — the cost centre returned to the project.)
  • Project delivery status is PMS-derived. A project's status is now the canonical deliveryStatus (BACKLOG / TODO / IN_PROGRESS / IN_REVIEW / DONE / CANCELLED), rolled up from the statuses of its linked PMS tickets via the org status mapping. It is read-only while the project has any PMS link and manually settable only when it has none. The REST Project lifecycleStageId field is replaced by deliveryStatus.

Removed ​

  • Configurable lifecycle stages. The standalone lifecycle-stage entity and its GET/POST/PATCH/DELETE /org/{orgId}/lifecycle-stages REST endpoints, the lifecycle-stages:read / lifecycle-stages:write scopes, and the lifecycle_stage webhook entity type are removed. Project delivery status now lives on the project itself as deliveryStatus (see Changed above).

v1.2.0 — 2026-05-12 ​

Contractor-filled vacancies + endDate-aware "currently filled" semantics.

For platform changes, see Flowstate Updates.

Added ​

  • POST /vacancies/:id/fill now supports filling with a contractor. Pass fillerType: "contractor" in the request body along with name, rate, rateType, and currencyCode. The endpoint creates a contractor record with an initial rate adjustment and transfers the vacancy's assignments to the new contractor. The response wraps both branches via mutually-exclusive employee / contractor fields. Existing employee-fill callers continue to work unchanged — fillerType defaults to "employee".
  • Vacancy.filledByLiveContractorId — new mutually-exclusive companion to filledByLiveEmployeeId. Set automatically by the contractor-branch fill, or manually via PATCH.
  • Vacancy.isFilled (derived) — true when one of the filledBy* FKs is set and the filler's endDate is unset or in the future. Once the filler's endDate passes, the vacancy is treated as open again (forecast cost resumes from that date). This replaces the previous "filledByLiveEmployeeId IS NULL" check throughout the forecast model.
  • Integration hook surface for positions — Custom-integration hooks that emit vacancy records can now use filledBy: { externalId } (or the shorthand filledByExternalId). The sync layer resolves the externalId against both live employees and live contractors and sets the appropriate FK. See Custom Integrations → Vacancies.

Changed ​

  • Vacancy filtering semantics — Default vacancy listings now hide currently-filled vacancies; pass excludeFilled=false to include them. Cost forecast views suppress a vacancy's cost only while its filler is active (matching isFilled), then resume contributing cost once the filler's endDate passes.

v1.1.0 — 2026-04-08 ​

Custom attributes, nested writes, and vacancy fill.

For platform changes, see Flowstate Updates.

Added ​

  • Custom attributes — Define custom fields on employees, contractors, vacancies, teams, and projects via GET/POST/PATCH/DELETE /custom-attributes. Custom attribute values are returned on all resource endpoints and can be set during create and update operations.
  • Nested create and update — Create or update child records inline. For example, create an employee and their team assignment in a single POST /employees request by including an assignments array in the body.
  • Vacancy fill endpoint — POST /vacancies/:id/fill converts a vacancy into an active employee or contractor record, closing the vacancy and transferring its assignments.
  • ?include= support — Use ?include=assignments,team,project on any resource endpoint to embed related records in the response, reducing round trips.
  • Cost centre filter — All list endpoints now accept costCentreId as a filter parameter.

Changed ​

  • Work Types renamed to Resource Types — The /work-types endpoint is now /resource-types. The previous path continues to work but is deprecated and will be removed in v2.0.0.

v1.0.0 — 2026-03-11 ​

Initial public release of the Flowstate Developer API.

Added ​

  • Employees — Full CRUD for employee records with salary, role, and geography data
  • Contractors — Full CRUD for external contractors with rate and contract period tracking
  • Vacancies — Full CRUD for open positions with salary ranges and hiring pipeline status
  • Teams — Full CRUD for organizational teams with hierarchy support
  • Projects — Full CRUD for projects with timelines and cost estimates
  • Assignments — Unified assignment model for employee, contractor, vacancy, and team allocations to teams and projects
  • Cost Centres — Full CRUD for cost centre management
  • Value Streams — Full CRUD for value stream organization
  • Work Types — Full CRUD for work type classification
  • Drivers — Full CRUD for strategic project drivers
  • Lifecycle Stages — Full CRUD for project lifecycle stage management
  • Exchange Rates — Full CRUD for currency conversion rates
  • Locations — Full CRUD for geographic location management
  • Scenario support — Pass scenarioId to any endpoint to operate within a what-if scenario
  • Pagination — Consistent page-based pagination with page, limit, search, sortBy, and sortDir
  • Authentication — API key-based authentication with scoped permissions
  • Error handling — Structured error responses with error codes and unique error IDs

Flowstate Documentation

Copyright 2026 Flowstate.