NovumOS Board Access API
The board-access API from NovumOS — 5 operation(s) for board-access.
The board-access API from NovumOS — 5 operation(s) for board-access.
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-board-access-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 Board Access API
description: Block-based kanban where agents are first-class users.
version: 0.0.0
tags:
- name: board-access
paths:
/v1/boards/{board_id}/access:
get:
tags:
- board-access
summary: Get Board Access
operationId: get_board_access_v1_boards__board_id__access_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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardAccessListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
post:
tags:
- board-access
summary: Post Board Access
operationId: post_board_access_v1_boards__board_id__access_post
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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GrantBoardAccessRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardGrantResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/boards/{board_id}/access/{user_id}:
patch:
tags:
- board-access
summary: Patch Board Access
operationId: patch_board_access_v1_boards__board_id__access__user_id__patch
parameters:
- name: board_id
in: path
required: true
schema:
type: string
format: uuid
title: Board Id
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
title: User 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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBoardAccessRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardGrantResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
delete:
tags:
- board-access
summary: Delete Board Access
operationId: delete_board_access_v1_boards__board_id__access__user_id__delete
parameters:
- name: board_id
in: path
required: true
schema:
type: string
format: uuid
title: Board Id
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
title: User 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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/boards/{board_id}/access:reclaim:
post:
tags:
- board-access
summary: Reclaim Board Access
description: 'Org-owner-only governance action: add (or raise to) the owner''s manager
grant. Non-owners get a uniform ``403`` (the service closes the existence
oracle before any board load). See ``reclaim_board``.'
operationId: reclaim_board_access_v1_boards__board_id__access_reclaim_post
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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardGrantResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/boards/{board_id}/invitations:
post:
tags:
- board-access
summary: Create Board Invitation
description: 'Invite an email address straight to **this board**. Board manager only.
One operator action for "share this board with my client''s reviewer": it
mints a pending **guest** invitation carrying the board grant, so accepting
creates the membership and the ``board_grants`` row in the same transaction
and the invitee lands on a workspace where the board is already there —
instead of the empty workspace §4.4 describes.
Board ``manager`` is the gate (§4.6''s sharing capability), **not** org
admin: a ``member`` who runs one client''s board can bring that client onto
it without being made an administrator of the whole workspace. A ``guest``
cannot — an external collaborator must not be able to staff, or spend the
seats of, a workspace they do not pay for (``403``).
Status codes carry the outcome: **201** for a new invitation, **200** for a
resend of a live one to the same board (the token is rotated, so the
previous link dies), and **200** with the ``invitation_noop`` shape when the
address already holds a membership — in which case the board grant is
applied immediately and rides along on the response, because the operator''s
intent ("share this board with them") is satisfiable right now without an
invitation. A pending invitation for a *different* board, or a workspace
invitation, is a ``409``: the two are different offers and neither may
silently overwrite the other.
This is **not** a share link. A share link (``POST
/v1/boards/{id}/share-links``) is seatless, identity-free and read-only —
the free way to let a client watch a board. This creates a real account with
attribution and comment/edit rights. §4.6 keeps both, and they are not
interchangeable.'
operationId: create_board_invitation_v1_boards__board_id__invitations_post
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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBoardInvitationRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/InvitationResponse'
- $ref: '#/components/schemas/AlreadyMemberResponse'
title: Response Create Board Invitation V1 Boards Board Id Invitations Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
get:
tags:
- board-access
summary: List Board Invitations
description: 'Invitations sent to this board. Board manager only.
Defaults to the pending slice — what the share dialog shows next to the
people who already have access, so an operator can tell "invited, waiting"
apart from "in". ``?status=all`` returns the history.'
operationId: list_board_invitations_v1_boards__board_id__invitations_get
parameters:
- name: board_id
in: path
required: true
schema:
type: string
format: uuid
title: Board Id
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
default: pending
title: Status
- 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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_InvitationResponse_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/boards/{board_id}/invitations/{invitation_id}:
delete:
tags:
- board-access
summary: Revoke Board Invitation
description: 'Withdraw a pending invitation to this board. Board manager only.
Exists alongside the admin-gated workspace revoke because the manager who
sent it may not be an org admin, and whoever can send has to be able to take
it back. Terminal and seatless — and since the grant materializes only at
accept, a revoked invitation leaves no board access behind.'
operationId: revoke_board_invitation_v1_boards__board_id__invitations__invitation_id__delete
parameters:
- name: board_id
in: path
required: true
schema:
type: string
format: uuid
title: Board Id
- name: invitation_id
in: path
required: true
schema:
type: string
format: uuid
title: Invitation 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.
- name: X-Novum-Org
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional. Selects the workspace this request acts in. An integration token is **pinned** to its own workspace, so a conflicting value returns `404`. For a browser session the value is re-checked against live membership on every request: it can only ever narrow to a workspace you already belong to, never widen. Omit it to act in the session''s active workspace.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
components:
schemas:
InvitationResponse:
properties:
object:
type: string
title: Object
default: invitation
id:
type: string
format: uuid
title: Id
org_id:
type: string
format: uuid
title: Org Id
org_name:
anyOf:
- type: string
- type: 'null'
title: Org Name
email:
type: string
title: Email
role:
type: string
title: Role
status:
type: string
title: Status
invited_by_user_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Invited By User Id
board_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Board Id
board_role:
anyOf:
- type: string
- type: 'null'
title: Board Role
board_name:
anyOf:
- type: string
- type: 'null'
title: Board Name
last4:
anyOf:
- type: string
- type: 'null'
title: Last4
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
created_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created Time
accepted_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Accepted At
declined_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Declined At
revoked_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Revoked At
type: object
required:
- id
- org_id
- email
- role
- status
title: InvitationResponse
description: 'One invitation, as the inviting workspace and the invitee both see it.
Deliberately **never** carries the token — the raw token exists exactly once,
in the email that was sent, and is not recoverable afterwards (only its
argon2id hash is stored). ``last4`` is included so an admin can correlate a
row with a support request without the token being disclosed, mirroring
``ShareLinkResponse``.
``org_name`` is populated on the invitee-facing reads
(``GET /v1/me/invitations``, accept/decline) because an invitee looking at a
workspace they have not joined has no other way to learn what they are being
asked to join; the admin-facing list leaves it ``None`` (the caller already
knows which workspace they are in).'
AccessUser:
properties:
object:
type: string
title: Object
default: user
id:
type: string
format: uuid
title: Id
kind:
type: string
title: Kind
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
avatar:
anyOf:
- type: string
- type: 'null'
title: Avatar
additionalProperties: false
type: object
required:
- id
- kind
title: AccessUser
description: The grantee, shaped like the Notion person reference (§5.1).
AlreadyMemberResponse:
properties:
object:
type: string
title: Object
default: invitation_noop
already_member:
type: boolean
title: Already Member
default: true
membership:
$ref: '#/components/schemas/MembershipResponse'
board_grant:
anyOf:
- $ref: '#/components/schemas/BoardGrantResponse'
- type: 'null'
type: object
required:
- membership
title: AlreadyMemberResponse
description: 'The §4.8 "an invitation to an existing member is a no-op" outcome.
Returned (HTTP **200**, not 201) when the invited address already holds a
live membership in the workspace. No invitation row is written and no seat
moves — the spec calls this "a no-op, not a duplicate row", so it is neither
an error nor a second invitation. The existing membership rides along so the
caller can render "they''re already in" without a follow-up request.'
MembershipResponse:
properties:
object:
type: string
title: Object
default: membership
id:
type: string
format: uuid
title: Id
user_id:
type: string
format: uuid
title: User Id
org_id:
type: string
format: uuid
title: Org Id
role:
type: string
title: Role
email:
anyOf:
- type: string
- type: 'null'
title: Email
name:
anyOf:
- type: string
- type: 'null'
title: Name
kind:
type: string
title: Kind
default: human
joined_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Joined At
last_signed_in_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Signed In At
type: object
required:
- id
- user_id
- org_id
- role
title: MembershipResponse
BoardAccessListResponse:
properties:
object:
type: string
title: Object
default: list
visibility:
type: string
title: Visibility
workspace_access:
type: string
title: Workspace Access
default: edit
permissions:
additionalProperties:
type: string
type: object
title: Permissions
your_role:
anyOf:
- type: string
- type: 'null'
title: Your Role
can_manage:
type: boolean
title: Can Manage
default: false
results:
items:
$ref: '#/components/schemas/BoardGrantResponse'
type: array
title: Results
additionalProperties: false
type: object
required:
- visibility
- results
title: BoardAccessListResponse
description: 'List of grants plus the board''s access posture (§4.6).
Includes the board''s ``visibility`` (NOV-195) and the ``workspace_access`` /
``permissions`` configuration (NOV-216) so a sharing client — REST or an MCP
agent — has the full picture in one call.
NOV-218: also carries the CALLER''s effective board role (``your_role``) and a
derived ``can_manage`` flag, so a client can gate manage affordances on the
backend''s real board-role resolution instead of approximating from org role.
``your_role`` is one of ``viewer``/``commenter``/``editor``/``manager`` (or
``None`` when the caller has no access — in practice never ``None`` here,
since listing already requires viewer); ``can_manage`` is exactly
``role_satisfies(your_role, "manager")``.'
GrantBoardAccessRequest:
properties:
user_id:
type: string
format: uuid
title: User Id
role:
type: string
title: Role
additionalProperties: false
type: object
required:
- user_id
- role
title: GrantBoardAccessRequest
UpdateBoardAccessRequest:
properties:
role:
type: string
title: Role
additionalProperties: false
type: object
required:
- role
title: UpdateBoardAccessRequest
BoardGrantResponse:
properties:
object:
type: string
title: Object
default: board_grant
id:
type: string
format: uuid
title: Id
user:
$ref: '#/components/schemas/AccessUser'
role:
type: string
title: Role
granted_by:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Granted By
granted_at:
type: string
format: date-time
title: Granted At
additionalProperties: false
type: object
required:
- id
- user
- role
- granted_at
title: BoardGrantResponse
PaginatedResponse_InvitationResponse_:
properties:
object:
type: string
title: Object
default: list
results:
items:
$ref: '#/components/schemas/InvitationResponse'
type: array
title: Results
has_more:
type: boolean
title: Has More
default: false
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
page_size:
type: integer
title: Page Size
default: 25
type: object
required:
- results
title: PaginatedResponse[InvitationResponse]
CreateBoardInvitationRequest:
properties:
email:
type: string
title: Email
board_role:
type: string
title: Board Role
default: commenter
additionalProperties: false
type: object
required:
- email
title: CreateBoardInvitationRequest
description: 'Invite an email address **straight to one board** (NOV-532, §4.6/§4.8).
The one-action form of "share this board with my client''s reviewer": it
mints a ``guest`` invitation that carries the board grant, so accepting
lands the person on a workspace where that board is already there instead of
the empty workspace §4.4 describes.
There is no org-role field on purpose. A board invitation always mints a
**guest** — the board-scoped, external-collaborator role. Someone who should
see the whole workspace is a member, and that is the workspace invite
(``POST /v1/orgs/{id}/invitations``), a different decision made in a
different place by an admin.
``board_role`` is one of ``viewer`` | ``commenter`` | ``editor``.
``manager`` is not invitable — see
:data:`app.models.invitation.VALID_INVITATION_BOARD_ROLES`.'
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).'