NovumOS Blocks API
The blocks API from NovumOS — 3 operation(s) for blocks.
The blocks API from NovumOS — 3 operation(s) for blocks.
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-blocks-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 Blocks API
description: Block-based kanban where agents are first-class users.
version: 0.0.0
tags:
- name: Blocks
paths:
/v1/blocks/{parent_id}/children:
get:
tags:
- Blocks
summary: List Block Children
description: Fetch a card's body tree, recursing up to ``depth`` levels (spec §6.4).
operationId: list_block_children_v1_blocks__parent_id__children_get
parameters:
- name: parent_id
in: path
required: true
schema:
type: string
format: uuid
title: Parent Id
- name: depth
in: query
required: false
schema:
type: integer
maximum: 10
minimum: 1
default: 1
title: Depth
- 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:
type: object
additionalProperties: true
title: Response List Block Children V1 Blocks Parent Id Children Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
patch:
tags:
- Blocks
summary: Append Block Children
description: 'Append a run of blocks under ``parent_id`` (card or block).
Optional ``after`` selects a sibling to insert AFTER (Notion shape);
otherwise blocks land at the end.
NOV-168: an optional ``Idempotency-Key`` header makes the append safe to
retry. Absent ⇒ today''s behavior (append normally). Present ⇒ a replay
with the same key returns the original response without re-appending.'
operationId: append_block_children_v1_blocks__parent_id__children_patch
parameters:
- name: parent_id
in: path
required: true
schema:
type: string
format: uuid
title: Parent 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/AppendBlocksRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Append Block Children V1 Blocks Parent Id Children Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/blocks/{block_id}:
patch:
tags:
- Blocks
summary: Update Block
description: 'Modify a block. ``If-Match`` is ACCEPTED but ADVISORY (NOV-169, spec §8.1).
Body blocks are server-authoritative last-write-wins: a stale/wrong
``If-Match`` never 412s, the write merges. The header is still read and
forwarded for back-compat (the frontend keeps sending it until P4/NOV-170);
``update_block_for_principal`` parses-and-ignores it.'
operationId: update_block_v1_blocks__block_id__patch
parameters:
- name: block_id
in: path
required: true
schema:
type: string
format: uuid
title: Block 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/UpdateBlockRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Update Block V1 Blocks Block Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
delete:
tags:
- Blocks
summary: Delete Block
description: Soft-archive a block + its descendants.
operationId: delete_block_v1_blocks__block_id__delete
parameters:
- name: block_id
in: path
required: true
schema:
type: string
format: uuid
title: Block 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/blocks/{block_id}:move:
post:
tags:
- Blocks
summary: Move Block
description: 'Re-parent and/or reorder a block (NOV-498, spec §8.2).
Mirrors ``POST /v1/cards/{id}:move``. Returns the moved block''s envelope —
the same shape ``PATCH /v1/blocks/{id}`` returns.
No ``If-Match`` here, unlike the card ``:move``: the body surface resolves
last-write-wins and never 412s (§8.1), and this endpoint postdates that
decision, so there is no legacy header to parse-and-ignore.'
operationId: move_block_v1_blocks__block_id__move_post
parameters:
- name: block_id
in: path
required: true
schema:
type: string
format: uuid
title: Block 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/MoveBlockRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Move Block V1 Blocks Block Id Move Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
components:
schemas:
UpdateBlockRequest:
properties:
type:
anyOf:
- type: string
- type: 'null'
title: Type
archived:
anyOf:
- type: boolean
- type: 'null'
title: Archived
additionalProperties: true
type: object
title: UpdateBlockRequest
description: '`PATCH /v1/blocks/{id}` body.
The shape mirrors Notion: a top-level key matching ``type`` carries the
new payload. ``archived`` toggles soft-delete. ``type`` is optional and
only used when changing block kind.
``extra="allow"`` is load-bearing — the type-key payload arrives as an
extra — so a stray ``parent`` key cannot be caught here by
``extra="forbid"``. It is rejected in ``update_block_for_principal``
instead (NOV-498), which keeps the failure a 400 in the Notion-shape error
envelope rather than pydantic''s 422, and catches MCP callers on the same
path as HTTP ones.'
AppendBlocksRequest:
properties:
children:
items:
$ref: '#/components/schemas/BlockInput'
type: array
maxItems: 100
minItems: 1
title: Children
after:
anyOf:
- type: string
format: uuid
- type: 'null'
title: After
additionalProperties: false
type: object
required:
- children
title: AppendBlocksRequest
description: '`PATCH /v1/blocks/{parent_id}/children` body.'
MoveBlockRequest:
properties:
parent:
$ref: '#/components/schemas/BlockParent'
after:
anyOf:
- type: string
format: uuid
- type: 'null'
title: After
additionalProperties: false
type: object
required:
- parent
title: MoveBlockRequest
description: '`POST /v1/blocks/{block_id}:move` body (NOV-498).
Mirrors ``POST /v1/cards/{id}:move``. ``parent`` names the destination —
another block in the same card, or the card itself (top level). ``after``
names the sibling to land behind.
**``after=None`` means FIRST**, which is the OPPOSITE of ``after`` on
``AppendBlocksRequest`` above (there it means "at the end", Notion''s
behaviour). The asymmetry is deliberate and documented in spec §8.2:
"make this the first child" has no other spelling, while "make it last" is
just ``after=<current last sibling>``.'
BlockInput:
properties:
object:
type: string
title: Object
default: block
type:
type: string
title: Type
additionalProperties: true
type: object
required:
- type
title: BlockInput
description: 'One node in a `PATCH /v1/blocks/{id}/children` request body.
Matches Notion''s append-children shape: ``{"object": "block", "type":
"paragraph", "paragraph": {...}}``. ``object`` is optional — clients
sometimes omit it.'
BlockParent:
properties:
type:
type: string
title: Type
card_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Card Id
block_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Block Id
additionalProperties: false
type: object
required:
- type
title: BlockParent
description: Parent reference for a block — either the card or another block.
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).'