Name: Read API
Creator: Roiva

Roiva serves a read API at https://roiva-staging.com/api/v1, for pulling an account's figures into a warehouse, a notebook or your own tooling.

The contract

The OpenAPI document is at /api/v1/openapi.json, and needs no token to read — point a client generator at it. It is produced from the routes and the serializers rather than written, so it cannot describe an endpoint that is not served. Every section below comes from that same document.

Connecting

Send a personal access token as an Authorization: Bearer header — the same token an MCP client uses, issued the same way (MCP tools covers that). It acts as the user who issued it, so removing them from the account stops it working.

curl https://roiva-staging.com/api/v1/roi \
  -H "Authorization: Bearer YOUR_TOKEN"

Reading a list

Every list answers with the same envelope, so the tables below describe a row rather than repeating the wrapper:

{
  "data": [ { "id": 1 } ],
  "page": { "next_cursor": "MjAyNi0wOS0yOA", "has_more": true }
}

Pass next_cursor back as cursor until has_more is false. The cursor walks (updated_at, id) oldest-change-first, so a row changed mid-walk is seen again rather than missed — a repeat an upsert absorbs. With updated_since beside it, that is an incremental sync: ask for what changed, walk forward, remember where you stopped.

What it will not do

Every endpoint reads. Nothing here records a cost, approves value or moves an initiative, and that is a fact about the routes rather than a promise: only GETs are declared, and a guard spec holds every route under /api to it.

Amounts are integer cents with the currency beside them, never a formatted string. Version 1 does not break: fields and endpoints are added, and removing or renaming one would be version 2. How Roiva calculates value is what the figures mean.

GET /api/v1/roi

Approved value, total cost, net value and the ratio between them, over a reporting window. The same computation the ROI dashboard reads, so the two cannot disagree.

Parameter	Type	What it means
window	stringoptional	The reporting window. Defaults to all. An unrecognized value is refused rather than answered for another period. One of: 1yr, 3yr, 5yr, all.
initiative_id	integeroptional	Narrow the figures to one initiative in this account. An id this account cannot see answers 404.

What it answers with.

Field	Type	What it is
scope	objectalways present	What these figures cover.
scope.type	string	Whether these figures cover the whole portfolio or one initiative. One of: portfolio, initiative.
scope.id	integer	The initiative's id, when the scope is an initiative.
scope.title	string	The initiative's title, when the scope is an initiative.
period	objectalways present	The stretch of time they cover.
period.window	string	The reporting window these figures cover.
period.label	string	How the app names that window to a reader.
period.from	string	First day covered, when the window resolves to explicit dates.
period.through	string	Last day covered, when the window resolves to explicit dates.
currency	stringalways present	ISO 4217 code every amount below is in.
approved_value_cents	integeralways present	Value that has been approved, in cents. Unapproved entries do not count.
total_cost_cents	integeralways present	Everything the initiatives in scope have cost, in cents.
net_value_cents	integeralways present	Approved value minus total cost, in cents.
roi	numbermay be null	Net value divided by total cost. Null when there is no cost to divide by, which is not the same as zero.
cost	objectalways present	total_cost_cents split into its one-time and running halves.
cost.capex_cents	integer	The one-time part of total cost, in cents.
cost.opex_cents	integer	The running part of total cost, in cents.

GET /api/v1/initiatives

Ordered oldest change first, so a caller can walk forward from where they stopped. Sample initiatives are left out unless asked for.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
include_sample	booleanoptional · default false	Include provisioned demo initiatives, which are left out by default. A warehouse that ingests them reports figures nobody spent.

What a row carries.

Field	Type	What it is
id	integeralways present	—
title	stringalways present	—
description	stringmay be null	—
hypothesis	stringmay be null	—
stage	stringalways present	Where it is in its lifecycle. One of: identified, reviewing, implementing, live, paused, completed, rejected, dismissed.
is_sample	booleanalways present	Provisioned demo data. Left out of lists unless include_sample=true, because a warehouse that ingests it reports figures nobody spent.
category	stringmay be null	—
priority	integermay be null	Lower is higher priority.
source	stringmay be null	How the initiative came to exist.
business_unit	stringmay be null	—
department	stringmay be null	—
gl_dimension_value	stringmay be null	—
owner	objectmay be null	Who, inside this account. Names, never email addresses.
owner.id	integer	—
owner.name	string	—
confidence_score	numbermay be null	—
roi_time_horizon_years	integermay be null	—
currency	stringmay be null	—
expected_capex_cents	integermay be null	Amount in cents, in the currency beside it.
expected_opex_cents	integermay be null	Amount in cents, in the currency beside it.
expected_cost_savings_cents	integermay be null	Amount in cents, in the currency beside it.
expected_revenue_uplift_cents	integermay be null	Amount in cents, in the currency beside it.
started_at	stringmay be null	—
went_live_at	stringmay be null	—
approved_at	stringmay be null	—
closed_at	stringmay be null	—
submitted_for_review_at	stringmay be null	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/cost_entries

What the account has spent, one row per entry, whoever or whatever recorded it. Ordered oldest change first.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
initiative_id	integeroptional	Only rows belonging to one initiative in this account.
period_from	stringoptional	The start of the window. Entries are matched on where their period begins, which is how Roiva's own reports slice a period: an entry belongs to the period it starts in, so a twelve-month entry beginning in January is in Q1 and in no other quarter. Asking for a quarter therefore returns the rows the dashboard counted for it. Either bound may be given on its own.
period_to	stringoptional	The end of the window, matched the same way — see period_from.

What a row carries.

Field	Type	What it is
id	integeralways present	—
initiative_id	integeralways present	—
amount_cents	integermay be null	Amount in cents, in the currency beside it.
currency	stringmay be null	—
cost_type	stringmay be null	Software, tokens, implementation, infrastructure and so on.
cost_category	stringalways present	Whether it is one-time or running. Follows from the type unless somebody changed it. One of: capex, opex.
period_start	stringmay be null	—
period_end	stringmay be null	—
vendor_id	integermay be null	The vendor this is spend with, and the field to group spend by — it is what Roiva's own Vendors page groups on. Resolved from vendor_name when the entry is written, so the two usually agree; they come apart when two vendors are merged, because that repoints vendor_id on the existing entries and leaves their names alone. One vendor's rows can then carry several names, and grouping on the name splits its spend. Null where no name was given, which Roiva reports apart rather than against a vendor.
vendor_name	stringmay be null	The name as it was recorded, which is free text: an abbreviation, a product name, or a spelling the vendor has since been merged out of.
description	stringmay be null	—
notes	stringmay be null	—
is_estimated	boolean	—
locked	boolean	In a closed accounting period, so no sync will change it.
source	object	Where the record came from: typed in, imported, or brought in by a connection.
source.type	stringmay be null	—
source.ref	stringmay be null	The id the originating system knows it by.
source.connection_id	integermay be null	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/value_entries

What the account's initiatives have returned. Only entries whose status is "approved" count toward reported ROI — see counts_toward_roi on each row.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
initiative_id	integeroptional	Only rows belonging to one initiative in this account.
status	stringoptional	Only entries with this status. Only "approved" counts toward reported ROI. One of: draft, calculated, reviewed, approved, disputed, archived.
period_from	stringoptional	The start of the window. Entries are matched on where their period begins, which is how Roiva's own reports slice a period: an entry belongs to the period it starts in, so a twelve-month entry beginning in January is in Q1 and in no other quarter. Asking for a quarter therefore returns the rows the dashboard counted for it. Either bound may be given on its own.
period_to	stringoptional	The end of the window, matched the same way — see period_from.

What a row carries.

Field	Type	What it is
id	integeralways present	—
initiative_id	integeralways present	—
amount_cents	integermay be null	Amount in cents, in the currency beside it.
currency	stringmay be null	—
status	stringalways present	Only "approved" counts toward reported ROI. The others are on their way there or were sent back, and summing every row gives a figure that disagrees with /roi. One of: draft, calculated, reviewed, approved, disputed, archived.
counts_toward_roi	booleanalways present	Whether this entry is in the reported figure. True exactly when status is "approved".
entry_type	stringmay be null	—
period_start	stringmay be null	—
period_end	stringmay be null	—
is_estimated	boolean	—
confidence_score	numbermay be null	—
quality_score	numbermay be null	—
notes	stringmay be null	What a person wrote about this figure in their own words — for a saving, typically what changed: their team's doing, or a vendor's pricing.
provenance	stringmay be null	Where the number came from, in one phrase: synced from a connection, calculated from a formula, or entered by hand.
calculation_version	integermay be null	Which version of the formula produced it.
formula_id	integermay be null	—
source	object	Where the record came from: typed in, imported, or brought in by a connection.
source.type	stringmay be null	—
source.ref	stringmay be null	The id the originating system knows it by.
source.connection_id	integermay be null	—
approved_at	stringmay be null	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/metrics

The metric definitions behind the figures: what each one measures, its type and its unit.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.

What a row carries.

Field	Type	What it is
id	integeralways present	—
metric_key	stringalways present	The canonical key, as the metric registry spells it.
name	stringalways present	—
description	stringmay be null	—
metric_type	stringmay be null	count, duration, percentage, currency and so on.
unit	stringmay be null	—
currency_metric	boolean	Whether its readings are money.
active	boolean	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/observations

The readings and baselines the value formulas run on. Ordered oldest change first.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
initiative_id	integeroptional	Only rows belonging to one initiative in this account.
metric_key	stringoptional	Only readings of one metric, by its canonical key.

What a row carries.

Field	Type	What it is
id	integeralways present	—
metric_id	integermay be null	—
metric_key	stringmay be null	—
initiative_id	integermay be null	—
value	numbermay be null	The reading itself, in the metric's unit.
role	stringmay be null	Whether it is a baseline or a reading.
baseline_method	stringmay be null	How a baseline was arrived at, when it is one.
observed_at	stringmay be null	—
period_start	stringmay be null	—
period_end	stringmay be null	—
is_estimated	boolean	—
sample_size	integermay be null	—
quality_score	numbermay be null	—
source	object	Where the record came from: typed in, imported, or brought in by a connection.
source.type	stringmay be null	—
source.ref	stringmay be null	The id the originating system knows it by.
source.connection_id	integermay be null	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/budgets

The signed-off budget, not the business case the initiatives list carries. One row per initiative, including initiatives with no budget — see `budgeted`, which says which rows belong in a variance total. Ordered oldest change first, by the initiative.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
include_sample	booleanoptional · default false	Include provisioned demo initiatives, which are left out by default. A warehouse that ingests them reports figures nobody spent.
initiative_id	integeroptional	Only rows belonging to one initiative in this account.
budgeted	booleanoptional · default false	Only initiatives that have an approved budget. Applied after the comparison runs, since it is not a column, so a page can come back shorter than limit while there are still more pages.

What a row carries.

Field	Type	What it is
initiative_id	integeralways present	—
budgeted	booleanalways present	Whether an approved budget exists at all. False means the figures below compare spend against nothing, so these rows belong out of any variance total — which is what Roiva's own totals do.
status	stringalways present	"over" when either half is over, because an unspent CapEx envelope early in a build must not hide an OpEx run rate that is already over. "scheduled" means a budget exists but has not started. One of: no_budget, scheduled, within, over.
over_parts	array of stringalways present	Which half is over, when status is "over". One of: capex, opex.
currency	stringmay be null	—
as_of	stringalways present	The day the comparison was made — today.
capex_budget_cents	integer	The current version's envelope.
capex_actual_cents	integer	CapEx spent since the budget began. Zero when budgeted is false: there is no budget window to measure over, so this is not the initiative's total spend. Read /api/v1/cost_entries for that.
capex_remaining_cents	integer	Negative when the envelope is exceeded.
opex_budget_to_date_cents	integer	Each month's rate summed from the month the budget began through this one, at whichever version covered each month. A revision changes the months after it and never restates the ones before.
opex_actual_cents	integer	OpEx spent since the budget began. Zero when budgeted is false: there is no budget window to measure over, so this is not the initiative's total spend. Read /api/v1/cost_entries for that.
budget_monthly_run_rate_cents	integer	The current version's rate, as a monthly figure.
actual_monthly_run_rate_cents	integermay be null	The average over the last 3 complete months the budget covered. Null until one complete month has passed.
budget_to_date_cents	integeralways present	CapEx envelope plus OpEx to date.
actual_to_date_cents	integeralways present	Zero when budgeted is false: there is no budget window to measure over, so this is not the initiative's total spend. Read /api/v1/cost_entries for that.
variance_cents	integeralways present	budget_to_date_cents minus actual_to_date_cents. Positive is under budget.
used_ratio	numbermay be null	Actual over budget to date. Null when there is no budget to date to divide by.
spent_before_budget_cents	integer	Spend dated before the month the budget began. Reported apart rather than charged against an envelope that did not exist yet, so it is in neither figure above.
opex_budget_fiscal_year_cents	integer	The whole fiscal year's OpEx budget.
opex_budget_fiscal_ytd_cents	integer	The part of it through as_of.
opex_actual_fiscal_ytd_cents	integer	—
budget_started_on	stringmay be null	The month the first approved version took effect.
revised	boolean	Whether the budget has been changed since it was first approved.
version_count	integer	—
revision_pending	boolean	A revision is waiting for the account Owner, because it would put the budget above the account's approval threshold. The figures here are still the approved ones.
current_version	objectmay be null	The approved version in effect, or null when there is no budget yet or every version starts in a later month.
current_version.id	integer	—
current_version.effective_from	string	The figures apply from the whole month containing this date, not from the day — so a version effective on the 28th covers that month in full, and budget_started_on is the first of it. There is no day proration.
current_version.ends_on	stringmay be null	The last month covered, again whole-month.
current_version.capex_cents	integer	A one-off total, not accrued.
current_version.opex_cents	integer	A rate, per opex_cadence.
current_version.opex_cadence	string	One of: monthly, quarterly, annually.
current_version.source	string	Whether it came from the initiative's approval, a later revision, or was set by hand. One of: approval, revision, manual.
current_version.reason	stringmay be null	Why it was set, in the words of whoever set it.
current_version.set_by	objectmay be null	Who, inside this account. Names, never email addresses.

GET /api/v1/decisions

Continue, scale, fix, pause or retire, with the rationale and the figures as they stood when it was decided. Immutable once written, so a row read today says what was known then. Ordered oldest change first.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
initiative_id	integeroptional	Only rows belonging to one initiative in this account.
outcome	stringoptional	Only decisions with this outcome. One of: continue, scale, fix, pause, retire.

What a row carries.

Field	Type	What it is
id	integeralways present	—
initiative_id	integermay be null	Null when the initiative it was about no longer exists. subject_title still says what it was.
subject_title	stringalways present	The initiative's title as it stood when the decision was made, so the row still reads after the initiative is renamed or gone.
outcome	stringalways present	What was decided. One of: continue, scale, fix, pause, retire.
outcome_label	stringalways present	How Roiva words the outcome on a page.
rationale	stringalways present	Why, in the words of whoever decided. Always present.
stage_before	stringalways present	One of: identified, reviewing, implementing, live, paused, completed, rejected, dismissed.
stage_after	stringalways present	One of: identified, reviewing, implementing, live, paused, completed, rejected, dismissed.
stage_changed	booleanalways present	Some outcomes leave the initiative where it was.
decided_at	stringmay be null	When it was decided, which is the date to report it under.
decided_by	objectmay be null	Who, inside this account. Names, never email addresses.
decided_by.id	integer	—
decided_by.name	string	—
next_review_on	stringmay be null	When this is meant to be looked at again. Roiva suggests a date from the outcome; whoever decided can change it.
currency	stringmay be null	—
approved_value_cents	integermay be null	Approved value at the moment of the decision. Approved only, as everywhere: this is the figure that was on the screen, not a recomputation.
cost_to_date_cents	integermay be null	Amount in cents, in the currency beside it.
net_cents	integermay be null	approved_value_cents minus cost_to_date_cents, as of the decision.
planned_value_cents	integermay be null	What the business case had promised in total.
planned_value_to_date_cents	integermay be null	The part of that plan due by the decision date.
roi	numbermay be null	The ratio as of the decision. Null where there was no cost to divide by.
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/integrations

What each connection is, whether it is working, and when data last arrived. Credentials, stored settings and error prose are never served — see the field descriptions for what stands in for them. Ordered oldest change first.

Parameter	Type	What it means
limit	integeroptional · default 100	Rows per page, up to 500.
cursor	stringoptional	The next_cursor from the previous page. Opaque: its shape is not part of the contract.
updated_since	stringoptional	Only rows changed at or after this moment, which is what makes a repeat pull cheap. At or after, not after, so a caller passing back the last updated_at they saw cannot miss a row saved in the same millisecond.
platform	stringoptional	Only connections to one platform.
status	stringoptional	Only connections in this state. One of: active, paused, error, disconnected.

What a row carries.

Field	Type	What it is
id	integeralways present	—
platform	stringalways present	Which system this connects to.
name	stringmay be null	—
description	stringmay be null	—
status	stringalways present	Whether it is working. "error" means syncs are failing; "paused" and "disconnected" mean somebody stopped it. One of: active, paused, error, disconnected.
auth_type	stringmay be null	How it authenticates. The credentials themselves are never served. One of: oauth, api_key, basic, webhook, github_app, service_account.
last_sync_status	stringmay be null	How the most recent sync ended.
last_synced_at	stringmay be null	When data last arrived. The field to watch: a connection can read "active" and still not have synced for a week.
reauth_required_at	stringmay be null	Set when the platform refused the grant Roiva holds. Non-null means no amount of retrying will fix it and a person has to reconnect.
external_account_id	stringmay be null	What the platform calls the account on its side, for joining to its own data.
external_account_name	stringmay be null	—
primary_source_categories	array of stringalways present	The categories this connection is the canonical source for. Where two connections could serve the same category, only the primary one's readings are used.
metric_categories	array of stringalways present	What this platform's connections can serve at all, whether or not this one is primary.
simulated	booleanalways present	A connection whose syncs are answered by Roiva's simulator rather than by the platform. Only an internal Roiva account can hold one.
connected_by	objectmay be null	Who, inside this account. Names, never email addresses.
connected_by.id	integer	—
connected_by.name	string	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.

GET /api/v1/initiatives/{id}

The same fields the list serves, for an initiative a caller already has the id of. An id belonging to another account answers 404 rather than 403, because a 403 would confirm it exists.

Parameter	Type	What it means
id	integerrequired	The initiative's Roiva id.

What it answers with.

Field	Type	What it is
id	integeralways present	—
title	stringalways present	—
description	stringmay be null	—
hypothesis	stringmay be null	—
stage	stringalways present	Where it is in its lifecycle. One of: identified, reviewing, implementing, live, paused, completed, rejected, dismissed.
is_sample	booleanalways present	Provisioned demo data. Left out of lists unless include_sample=true, because a warehouse that ingests it reports figures nobody spent.
category	stringmay be null	—
priority	integermay be null	Lower is higher priority.
source	stringmay be null	How the initiative came to exist.
business_unit	stringmay be null	—
department	stringmay be null	—
gl_dimension_value	stringmay be null	—
owner	objectmay be null	Who, inside this account. Names, never email addresses.
owner.id	integer	—
owner.name	string	—
confidence_score	numbermay be null	—
roi_time_horizon_years	integermay be null	—
currency	stringmay be null	—
expected_capex_cents	integermay be null	Amount in cents, in the currency beside it.
expected_opex_cents	integermay be null	Amount in cents, in the currency beside it.
expected_cost_savings_cents	integermay be null	Amount in cents, in the currency beside it.
expected_revenue_uplift_cents	integermay be null	Amount in cents, in the currency beside it.
started_at	stringmay be null	—
went_live_at	stringmay be null	—
approved_at	stringmay be null	—
closed_at	stringmay be null	—
submitted_for_review_at	stringmay be null	—
created_at	stringalways present	When the row was first written.
updated_at	stringalways present	When it last changed. This is what the list is ordered by, what a cursor points into, and what updated_since compares against.