Skip to content
Guides

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.

Download the OpenAPI document

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 object
tokenReadsAmountsboolean

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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

periodobject
currencystring
amountsHiddenstring
Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsboolean
cardsarray of object
showninteger
ofinteger
projectsarray of object

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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 · required
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

periodobject
currencystring
amountsHiddenstring
Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsboolean
cardsarray of object
projectobject

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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

periodobject
currencystring
amountsHiddenstring
Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsboolean
cardsarray of object
groupstring
The grouping applied: one project is grouped by provider.One of: provider, service, project
totalinteger | null
rowsarray of object
The whole table: each provider, then its services.
groupsarray of object
The table split by `group`, largest first.

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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

periodobject
currencystring
amountsHiddenstring
Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsboolean
cardsarray of object
movementsarray of object
byProjectarray of object

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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
tokenReadsAmountsboolean
obligationsarray of object

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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

periodobject
currencystring
amountsHiddenstring
Whether amounts are hidden from this answer: for none, some or all of its projects.One of: none, some, all
tokenReadsAmountsboolean
cardsarray of object
incidentsarray of object

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More 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

periodobject
incidentsarray of object

Errors

  • 400 The query isn't valid (`code` says which part).
  • 401 No token, or one that is unknown, expired, revoked, or beyond its creator's access now.
  • 403 The workspace is suspended.
  • 404 A project this token doesn't read, or one that doesn't exist.
  • 429 More than 60 requests a minute with this token; `Retry-After` says when to try again.