NovumOS Public API
The public API from NovumOS — 7 operation(s) for public.
The public API from NovumOS — 7 operation(s) for public.
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-public-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 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).'