API reference
Read a workspace's figures from your own scripts and tools. Every endpoint is read-only and answers JSON.
Authentication
Make a workspace API token in Settings → API, and send it as a bearer token: Authorization: Bearer sv_api_…. A token reads what its creator can read now, within the projects and amounts it was given.
Limits
60 requests a minute per token, shared with MCP. Over it, the answer is 429 with Retry-After.
The OpenAPI document
This page is drawn from the same OpenAPI 3.1 document the API serves, so a client generator can read it too.
For an agent, the same reads come through the MCP server. Connect your agent
Endpoints
The projects this token reads
GET /api/v1/public/projects
Parameters
No parameters.
Returns
projectsarray of objecttokenReadsAmountsboolean
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
The portfolio's figures and projects for a period
GET /api/v1/public/portfolio
Parameters
periodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
Returns
periodobjectcurrencystringamountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleancardsarray of objectshownintegerofintegerprojectsarray of object
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
One project's figures for a period
GET /api/v1/public/projects/{projectId}/summary
Parameters
projectIdpath · requiredperiodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
Returns
periodobjectcurrencystringamountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleancardsarray of objectprojectobject
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
Costs by provider, service or project for a period
GET /api/v1/public/costs
Parameters
periodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
projectquery- One project's id; default: every project the token reads.
groupquery- provider (the default), service or project.One of: provider, service, project
Returns
periodobjectcurrencystringamountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleancardsarray of objectgroupstring- The grouping applied: one project is grouped by provider.One of: provider, service, project
totalinteger | nullrowsarray of object- The whole table: each provider, then its services.
groupsarray of object- The table split by `group`, largest first.
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
Revenue, MRR movements and each project's share for a period
GET /api/v1/public/revenue
Parameters
periodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
projectquery- One project's id; default: every project the token reads.
Returns
periodobjectcurrencystringamountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleancardsarray of objectmovementsarray of objectbyProjectarray of object
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
Renewals and expiries due soon
GET /api/v1/public/obligations
Parameters
projectquery- One project's id; default: every project the token reads.
daysquery- Due within this many days, 0–90 (default 90); overdue ones are always included.
Returns
amountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleanobligationsarray of object
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
Uptime, checks and incidents for a period
GET /api/v1/public/health
Parameters
periodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
projectquery- One project's id; default: every project the token reads.
Returns
periodobjectcurrencystringamountsHiddenstring- Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsbooleancardsarray of objectincidentsarray of object
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.
Open or recent incidents
GET /api/v1/public/incidents
Parameters
periodquery- The period: 7d, 30d (the default), 90d, 12m, mtd, qtd, ytd, or custom.One of: 7d, 30d, 90d, 12m, mtd, qtd, ytd, custom
fromquery- With period=custom: the first day (YYYY-MM-DD).
toquery- With period=custom: the last day (YYYY-MM-DD).
currencyquery- ISO 4217; one the workspace holds amounts in. Default: the reporting currency.
projectquery- One project's id; default: every project the token reads.
statusquery- open (the default), resolved, or all.One of: open, resolved, all
Returns
periodobjectincidentsarray of object
Errors
400The query isn't valid (`code` says which part).401No token, or one that is unknown, expired, revoked, or beyond its creator's access now.403The workspace is suspended.404A project this token doesn't read, or one that doesn't exist.429More than 60 requests a minute with this token; `Retry-After` says when to try again.