NovumOS Billing API
The billing API from NovumOS — 3 operation(s) for billing.
The billing API from NovumOS — 3 operation(s) for billing.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/novumos-app:novumos-app-billing-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NovumOS Billing API
description: Block-based kanban where agents are first-class users.
version: 0.0.0
tags:
- name: Billing
paths:
/v1/orgs/{org_id}/billing:
get:
tags:
- Billing
summary: Get Billing
description: 'Return the org''s billing status object (spec §18.9).
Owner-only. ``billable_seats`` and the humans/agents ``seat_breakdown`` are
recomputed **live** via :func:`seat_breakdown` — never the stale
``billing_seats`` cache; the total derives from the breakdown''s counts so
they agree by construction (the first-agent-free math is server-side). On
a free org, ``current_period_end``/``cancel_at_period_end`` are null and
``has_payment_method`` is always false (spec §18.9 invariant), even if the
org retains a ``stripe_customer_id`` from a prior Pro subscription (§18.7
only clears the subscription id on cancel). On Pro, ``has_payment_method``
is derived offline from the Stripe customer id; no live Stripe call is made.'
operationId: get_billing_v1_orgs__org_id__billing_get
parameters:
- name: org_id
in: path
required: true
schema:
type: string
format: uuid
title: Org Id
- name: X-Board-Version
in: header
required: true
schema:
type: string
default: '2026-06-19'
description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BillingResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/orgs/{org_id}/billing:checkout:
post:
tags:
- Billing
summary: Checkout
description: 'Start a Stripe Checkout to upgrade the org to Pro (spec §18.6 / §18.5).
Owner-only (``admin`` is not sufficient — §18.1). Accepts an optional
``{"interval": "annual"|"monthly"}`` body (NOV-242) selecting the billing
cadence; an omitted body defaults to ``annual`` (the promoted option, §18.1).
Returns a ``{"checkout_url": …}`` the owner is redirected to. Errors:
* ``409`` if the org is already Pro (nothing to check out).
* ``503 billing_unconfigured`` if Stripe isn''t configured (dev has no keys),
surfaced by :func:`~app.core.stripe_client.get_stripe`.
The plan flip to Pro is **webhook-driven** (``checkout.session.completed`` →
§18.7), never set here. The router stays thin; the Customer-create /
session-create logic lives in :func:`create_checkout_session`.'
operationId: checkout_v1_orgs__org_id__billing_checkout_post
parameters:
- name: org_id
in: path
required: true
schema:
type: string
format: uuid
title: Org Id
- name: X-Board-Version
in: header
required: true
schema:
type: string
default: '2026-06-19'
description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/CheckoutRequest'
- type: 'null'
title: Payload
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/orgs/{org_id}/billing:portal:
post:
tags:
- Billing
summary: Portal
description: 'Open a Stripe Customer Portal session for the org (spec §18.6).
Owner-only (``admin`` is not sufficient — §18.1). Returns a
``{"portal_url": …}`` the owner is redirected to. Errors:
* ``409 no_subscription`` if the org has no ``stripe_customer_id`` (must
complete Checkout first to create the Stripe Customer).
* ``503 billing_unconfigured`` if Stripe isn''t configured (dev has no keys),
surfaced by :func:`~app.core.stripe_client.get_stripe`.
The router stays thin; the portal session logic lives in
:func:`create_portal_session`.'
operationId: portal_v1_orgs__org_id__billing_portal_post
parameters:
- name: org_id
in: path
required: true
schema:
type: string
format: uuid
title: Org Id
- name: X-Board-Version
in: header
required: true
schema:
type: string
default: '2026-06-19'
description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PortalResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
components:
schemas:
CheckoutRequest:
properties:
interval:
type: string
enum:
- annual
- monthly
title: Interval
default: annual
type: object
title: CheckoutRequest
description: 'Body for ``POST /v1/orgs/{org_id}/billing:checkout`` (spec §18.6, NOV-242).
``interval`` selects the billing cadence for the Pro subscription: ``"annual"``
(the promoted default — §18.1) or ``"monthly"`` (the deliberate premium). It
determines which of the four per-kind Stripe prices Checkout uses. The body is
optional on the wire; an omitted body defaults to annual.'
BillingResponse:
properties:
object:
type: string
title: Object
default: billing
org_id:
type: string
format: uuid
title: Org Id
plan:
type: string
title: Plan
status:
type: string
title: Status
billable_seats:
type: integer
title: Billable Seats
seat_breakdown:
$ref: '#/components/schemas/SeatBreakdown'
free_caps:
$ref: '#/components/schemas/FreeCaps'
current_period_end:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Current Period End
cancel_at_period_end:
anyOf:
- type: boolean
- type: 'null'
title: Cancel At Period End
has_payment_method:
type: boolean
title: Has Payment Method
default: false
governance_enabled:
type: boolean
title: Governance Enabled
default: false
type: object
required:
- org_id
- plan
- status
- billable_seats
- seat_breakdown
- free_caps
title: BillingResponse
description: 'Billing status object for ``GET /v1/orgs/{org_id}/billing`` (spec §18.9).
``billable_seats`` is the **live** count (``count_billable_seats``), never
the denormalized ``billing_seats`` cache. ``seat_breakdown`` is the
server-computed humans/agents split (the first-agent-free math lives there,
not the client — NOV-189). On a free org ``current_period_end`` and
``cancel_at_period_end`` are null and ``has_payment_method`` is false.'
SeatBreakdown:
properties:
humans:
type: integer
title: Humans
agents:
type: integer
title: Agents
billable_agents:
type: integer
title: Billable Agents
guests:
type: integer
title: Guests
default: 0
guest_allowance:
type: integer
title: Guest Allowance
default: 0
free_guests:
type: integer
title: Free Guests
default: 0
billable_guests:
type: integer
title: Billable Guests
default: 0
type: object
required:
- humans
- agents
- billable_agents
title: SeatBreakdown
description: "Seat split for the People/Billing UI (spec §18.9 / §18.14, NOV-189/NOV-533).\n\nComputed server-side from ``billing.seat_breakdown`` so neither the \"first\nagent free\" rule (§18.1) nor the guest allowance (§18.14) is ever re-derived\nin the frontend — clients render this split **verbatim**.\n\n* ``humans`` — non-guest human members. Guests are NOT included (§18.14).\n* ``guests`` — ``role='guest'`` members (§4.4 external collaborators).\n* ``guest_allowance`` = ``max(humans, free_caps.max_human_seats)`` — the\n free guest room, which floats with paid headcount.\n* ``free_guests`` / ``billable_guests`` — guests inside / beyond it. A\n billable guest bills on the **human** seat price; there is no guest SKU.\n* ``billable_agents`` = ``max(0, agents - 1)``.\n\nThe top-level ``billable_seats`` on :class:`BillingResponse` equals\n``humans + billable_guests + billable_agents``. §18.14: \"the org sees the\ncount before it is charged for it\" — this is that surface."
PortalResponse:
properties:
portal_url:
type: string
title: Portal Url
type: object
required:
- portal_url
title: PortalResponse
description: 'Response for ``POST /v1/orgs/{org_id}/billing:portal`` (spec §18.6).
The owner is redirected to ``portal_url`` (a Stripe-hosted Customer Portal
Session) to manage their subscription — cancel, update payment method, view
invoices. Requires an existing ``stripe_customer_id`` (``409 no_subscription``
if absent).'
CheckoutResponse:
properties:
checkout_url:
type: string
title: Checkout Url
type: object
required:
- checkout_url
title: CheckoutResponse
description: 'Response for ``POST /v1/orgs/{org_id}/billing:checkout`` (spec §18.6).
The owner is redirected to ``checkout_url`` (a Stripe-hosted Checkout
Session) to enter payment details. The plan flip to Pro is **webhook-driven**
(``checkout.session.completed`` → §18.7), never set by this endpoint — the
redirect can be lost, the webhook can''t.'
FreeCaps:
properties:
max_human_seats:
type: integer
title: Max Human Seats
max_agents:
type: integer
title: Max Agents
max_guests:
type: integer
title: Max Guests
default: 0
type: object
required:
- max_human_seats
- max_agents
title: FreeCaps
description: 'Free-tier caps surfaced to the client (spec §18.1 / §18.9).
Mirrors ``settings.free_max_human_seats`` / ``free_max_agents`` so the
frontend can render the upgrade prompt without hardcoding 5/1. Boards are
uncapped on Free (NOV-242), so there is no board field.
``max_guests`` (NOV-533, §18.14) is the third Free cap — the one the
``402 plan_limit_reached`` with ``limit.resource="guests"`` actually cites.
Unlike its two siblings it is **dynamic**: the guest allowance is
``max(humans, max_human_seats)``, so a grandfathered Free org with 8 humans
gets 8 guest slots, not 5. It equals ``seat_breakdown.guest_allowance`` by
construction (both come from the one server-side formula). On **Pro** it is
still reported — guests there are counted, never capped — so read it as
"the free guest allowance", which is what caps Free and what bills beyond
on Pro.'
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
IntegrationToken:
type: http
scheme: bearer
description: 'Integration token. Mint one in the app under **Settings → Integrations** and paste the `nov_…` value here. It is sent as `Authorization: Bearer nov_…`, the same credential the API enforces. Browser session cookies are NOT used by try-it-out (the cookie flow additionally requires an `X-CSRF-Token` header this page cannot mint).'