NovumOS Billing API

The billing API from NovumOS — 3 operation(s) for billing.

GitHub OpenAPI

Operations 3

GET /v1/orgs/{org_id}/billing Get Billing #
POST /v1/orgs/{org_id}/billing:checkout Checkout #
POST /v1/orgs/{org_id}/billing:portal Portal #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/novumos-app:novumos-app-billing-api"
All apis
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.

Get an API 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 Specification

novumos-app-billing-api-openapi.yml Raw ↑
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).'