NovumOS Public API

The public API from NovumOS — 7 operation(s) for public.

GitHub OpenAPI

Operations 7

GET /v1/public/config Get Public Config #
GET /v1/public/boards/{board_id} Get Public Board #
GET /v1/public/share/{token} Get Public Board By Token #
GET /v1/public/invitations/{token} Get Invitation By Token #
POST /v1/public/boards/{board_id}/cards/{card_id}/comments Create Public Comment #
GET /v1/public/boards/{board_id}/agent-activity Get Public Agent Activity #
GET /v1/public/share/{token}/agent-activity Get Public Agent Activity By Token #

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-public-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-public-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NovumOS Public API
  description: Block-based kanban where agents are first-class users.
  version: 0.0.0
tags:
- name: Public
paths:
  /v1/public/config:
    get:
      tags:
      - Public
      summary: Get Public Config
      description: 'Publish the runtime policy an unauthenticated client needs (NOV-512).


        Deliberately NOT folded into ``/healthz``: that route is ops/meta (liveness,

        build sha, migration state) and this is a product contract the SPA reads on

        the signup and password-reset forms. Keeping them apart also keeps this one

        inside ``/v1``, so it carries the same ``X-Board-Version`` gate and the same

        versioning promise as every other client-facing read.


        The handler resolves no principal and reads no org-scoped table: the

        response is identical for every caller on a deploy and can never leak

        tenant data. (The app-level dependencies — ``enforce_billing_writable`` and

        friends — do take a ``db`` session, but the Session is lazy and their org

        lookups are gated on ``principal.org_id``, which is ``None`` for anonymous

        traffic: no query runs, no connection is checked out.)

        Values come from :func:`app.services.auth.password_policy`, the same

        function ``validate_password_strength`` validates through — so an operator

        who overrides ``PASSWORD_MIN_LENGTH`` moves the client''s rules with the

        server''s instead of leaving them stale.'
      operationId: get_public_config_v1_public_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicConfigResponse'
      parameters:
      - 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.
  /v1/public/boards/{board_id}:
    get:
      tags:
      - Public
      summary: Get Public Board
      description: 'Read a shared board (board-scoped): metadata, columns, non-archived cards.


        Programmatic / back-compat surface — the token rides as the ``token`` query

        param and the path pins the board. Kept for callers that already hold a

        board id; the client-facing web route uses the token-only sibling below.'
      operationId: get_public_board_v1_public_boards__board_id__get
      parameters:
      - name: board_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Board 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:
                type: object
                additionalProperties: true
                title: Response Get Public Board V1 Public Boards  Board Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/public/share/{token}:
    get:
      tags:
      - Public
      summary: Get Public Board By Token
      description: 'Resolve a share-link ``token`` and serve ITS bound board (token-only, NOV-200).


        The client-facing share URL is ``{app_base_url}/share/{token}`` (a web route

        rendering the read-only board); this endpoint backs it. The token resolver

        is board-agnostic — it resolves the raw token via the ``last4`` index +

        argon2 verify and returns a principal carrying the bound ``board_id`` — so

        we serve the principal''s OWN board with no board id in the URL.


        404 (never reveal) when the token is absent, malformed, unknown, expired, or

        revoked. The bound org is set as the tenant scope so the board/card queries

        are org-filtered; board *access* is still granted only on the bound board by

        ``require_board_access`` inside :func:`_public_board_payload`.'
      operationId: get_public_board_by_token_v1_public_share__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - 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:
                type: object
                additionalProperties: true
                title: Response Get Public Board By Token V1 Public Share  Token  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/public/invitations/{token}:
    get:
      tags:
      - Public
      summary: Get Invitation By Token
      description: 'Resolve an emailed invitation token to its preview (unauthenticated, §4.8).


        Backs the ``{app_base_url}/invitations/{token}`` deep link the invitation

        email carries. The recipient has to be able to see *which workspace is

        asking* before deciding whether to sign in — or create an account at all —

        so this read cannot require a session. It is unauthenticated but not

        unauthorized: the token IS the credential, argon2id-hashed at rest and

        resolvable only while the invitation is pending.


        404 — never a distinguishable error — when the token is absent, malformed,

        unknown, expired, revoked, or already used. All six look identical, so the

        endpoint is not an oracle for guessing tokens, and the payload deliberately

        says nothing about whether the invited address has an account: presenting a

        valid token must not become account enumeration either.


        Accepting still requires signing in as the invited address

        (``POST /v1/invitations/{id}:accept``). This endpoint only tells the SPA

        which invitation to accept and whom to ask the visitor to sign in as.'
      operationId: get_invitation_by_token_v1_public_invitations__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - 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/InvitationPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/public/boards/{board_id}/cards/{card_id}/comments:
    post:
      tags:
      - Public
      summary: Create Public Comment
      description: 'Post a comment through a ``commenter`` share link.


        ``require_board_access(min_role=''commenter'')`` rejects a ``viewer`` link with

        403 and a cross-board token with 404. The card must live on the bound board.

        The comment is authored anonymously (no User, no seat).


        The app-level ``enforce_billing_writable`` dependency falls out at its "no

        principal" gate for a share-link token (it isn''t a bearer), so the §18.8

        read-only-when-past_due invariant is enforced here explicitly: a past_due org

        refuses this write with the same ``402 billing_past_due`` an internal write

        returns. Checked after the role gate so a ``viewer`` link still 403s (and an

        unauthorized caller never learns the org''s billing state).'
      operationId: create_public_comment_v1_public_boards__board_id__cards__card_id__comments_post
      parameters:
      - name: board_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Board Id
      - name: card_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Card 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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicCommentRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/public/boards/{board_id}/agent-activity:
    get:
      tags:
      - Public
      summary: Get Public Agent Activity
      description: 'Client-shareable, read-only agent-activity report for a shared board (NOV-271).


        Board-scoped surface: the token rides as ``?token=`` and the path pins the

        board. A viewer OR commenter token for THIS board sees the all-agents rollup;

        a cross-board / expired / revoked token 404s (existence hidden); an

        un-entitled org 403s ``governance_not_entitled`` AFTER the board gate. GATED

        to the Scale/Agency tier (the agency''s entitlement). ``window`` is ``24h`` or

        ``7d`` (400 otherwise).'
      operationId: get_public_agent_activity_v1_public_boards__board_id__agent_activity_get
      parameters:
      - name: board_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Board Id
      - name: window
        in: query
        required: false
        schema:
          type: string
          default: 24h
          title: Window
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - 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/PublicAgentActivityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/public/share/{token}/agent-activity:
    get:
      tags:
      - Public
      summary: Get Public Agent Activity By Token
      description: 'Token-only sibling of :func:`get_public_agent_activity` (NOV-200 pattern).


        Resolves the share-link ``token`` board-agnostically and serves the report

        for ITS bound board — no board id in the URL, mirroring

        :func:`get_public_board_by_token`. Same gates, same 404-on-invalid-token

        contract.'
      operationId: get_public_agent_activity_by_token_v1_public_share__token__agent_activity_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: window
        in: query
        required: false
        schema:
          type: string
          default: 24h
          title: Window
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - 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/PublicAgentActivityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentActivitySummary:
      properties:
        object:
          type: string
          title: Object
          default: agent_activity_summary
        by_action:
          additionalProperties:
            type: integer
          type: object
          title: By Action
        errors:
          type: integer
          title: Errors
        window:
          type: string
          title: Window
      type: object
      required:
      - by_action
      - errors
      - window
      title: AgentActivitySummary
      description: 'Rollup line for the activity drawer — "47 drafts, 3 card-moves, 0 errors · 24h".


        ``by_action`` maps a human label (``draft`` / ``card-move`` / ``card-create``

        / ``card-update``) to its count within ``window``. ``errors`` = ledger

        failures (0 in MVP) PLUS ``agent.request_denied`` budget denials in-window

        (see :func:`app.services.agent_ledger.agent_activity_summary`).'
    AgentActivityEntry:
      properties:
        object:
          type: string
          title: Object
          default: agent_activity_entry
        action:
          type: string
          title: Action
        label:
          type: string
          title: Label
        board_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Board Id
        card_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Card Id
        outcome:
          type: string
          title: Outcome
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - action
      - label
      - outcome
      - created_at
      title: AgentActivityEntry
      description: One reverse-chron feed row — a single successful agent action.
    PasswordPolicy:
      properties:
        object:
          type: string
          title: Object
          default: password_policy
        min_length:
          type: integer
          title: Min Length
        require_letter_and_digit:
          type: boolean
          title: Require Letter And Digit
      type: object
      required:
      - min_length
      - require_letter_and_digit
      title: PasswordPolicy
      description: 'The rules ``app.services.auth.validate_password_strength`` enforces.


        Built by :func:`app.services.auth.password_policy` from the same settings

        the validator reads, so the published policy cannot describe a rule the API

        does not actually apply.'
    CommentResponse:
      properties:
        object:
          type: string
          title: Object
          default: comment
        id:
          type: string
          format: uuid
          title: Id
        card_id:
          type: string
          format: uuid
          title: Card Id
        author_user_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Author User Id
        body:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Body
        is_archived:
          type: boolean
          title: Is Archived
        is_edited:
          type: boolean
          title: Is Edited
        created_time:
          type: string
          format: date-time
          title: Created Time
        last_edited_time:
          type: string
          format: date-time
          title: Last Edited Time
        etag:
          type: integer
          title: Etag
        parent:
          additionalProperties: true
          type: object
          title: Parent
          readOnly: true
        created_by:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Created By
          readOnly: true
        rich_text:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Rich Text
          readOnly: true
      additionalProperties: false
      type: object
      required:
      - id
      - card_id
      - body
      - is_archived
      - is_edited
      - created_time
      - last_edited_time
      - etag
      - parent
      - created_by
      - rich_text
      title: CommentResponse
    InvitationPreviewResponse:
      properties:
        object:
          type: string
          title: Object
          default: invitation_preview
        invitation_id:
          type: string
          format: uuid
          title: Invitation Id
        org_id:
          type: string
          format: uuid
          title: Org Id
        org_name:
          type: string
          title: Org Name
        org_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Slug
        email:
          type: string
          title: Email
        role:
          type: string
          title: Role
        board_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Board Name
        board_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Board Role
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
      - invitation_id
      - org_id
      - org_name
      - email
      - role
      - expires_at
      title: InvitationPreviewResponse
      description: 'What an emailed invitation token resolves to, before anyone signs in.


        Backs ``GET /v1/public/invitations/{token}``, which the ``/invitations/

        {token}`` deep link in the invite email lands on: it tells the SPA which

        workspace is asking, which address the invitation is addressed to (so the

        sign-in/sign-up form can be pre-filled and the "wrong account" case can be

        explained), and the invitation id to accept by. It carries no member

        directory, no org id beyond what the invitee is being offered, and nothing

        about whether the address already has an account — presenting a valid token

        must not become an account-enumeration oracle.'
    PublicConfigResponse:
      properties:
        object:
          type: string
          title: Object
          default: public_config
        password:
          $ref: '#/components/schemas/PasswordPolicy'
      type: object
      required:
      - password
      title: PublicConfigResponse
      description: Envelope for the unauthenticated runtime-config read.
    PublicAgentActivityResponse:
      properties:
        object:
          type: string
          title: Object
          default: public_agent_activity
        board_id:
          type: string
          format: uuid
          title: Board Id
        summary:
          $ref: '#/components/schemas/AgentActivitySummary'
        entries:
          items:
            $ref: '#/components/schemas/AgentActivityEntry'
          type: array
          title: Entries
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - board_id
      - summary
      - entries
      title: PublicAgentActivityResponse
      description: 'Client-shareable, read-only agent-activity report for ONE board (NOV-271).


        Served on the seatless share-link surface (``/v1/public/...``) so an agency

        can show a CLIENT holding a viewer/commenter share-link token exactly what

        agents did on THEIR board — the "run bots on a client board and show that

        client what happened" trust flow (spec §4.6 + §4.7). Deliberately narrower

        than :class:`AgentActivityResponse`: it is ALWAYS board-scoped (``board_id``

        is the bound board, never org-wide) and all-agents (no ``agent_user_id`` — a

        client sees the board''s activity, not internal per-agent breakdowns). No

        ``page_size`` — the feed is still cursor-paginated via ``next_cursor``.'
    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
    PublicCommentRequest:
      properties:
        body:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Body
      additionalProperties: false
      type: object
      required:
      - body
      title: PublicCommentRequest
      description: 'A comment posted through a ``commenter`` share link (NOV-199).


        Only the block ``body`` is accepted — the card is fixed by the path and the

        author is the (anonymous) link, never a User. Emptiness is enforced in the

        comment service.'
  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).'