NovumOS Feedback API
The feedback API from NovumOS — 4 operation(s) for feedback.
The feedback API from NovumOS — 4 operation(s) for feedback.
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-feedback-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 Feedback API
description: Block-based kanban where agents are first-class users.
version: 0.0.0
tags:
- name: Feedback
paths:
/v1/feedback:
post:
tags:
- Feedback
summary: Submit Feedback
description: 'Submit one feedback report (spec §25.4).
The share-link refusal, the workspace resolution and the hourly caps all run
in ``require_submit_context`` — a dependency, so they run before the body is
validated (see the module docstring). It hands back the resolved ``org_id``,
which is what the row is stamped with.
``surface`` is derived from HOW the caller authenticated, not claimed by
them: an integration token is the ``api`` surface, a browser session is
``web``. (``mcp`` is set by the §25.11 tools.)'
operationId: submit_feedback_v1_feedback_post
parameters:
- name: org_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
title: Org Id
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
- 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/CreateFeedbackRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
get:
tags:
- Feedback
summary: List Own Feedback
description: List the caller's OWN submissions, newest first (spec §25.4).
operationId: list_own_feedback_v1_feedback_get
parameters:
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by feedback type.
title: Type
description: Filter by feedback type.
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by triage status.
title: Status
description: Filter by triage status.
- name: page_size
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 25
title: Page Size
- name: start_cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Start Cursor
- name: org_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
title: Org Id
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
- 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 Own Feedback V1 Feedback Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/feedback/screenshots:presign:
post:
tags:
- Feedback
summary: Presign Feedback Screenshot
description: 'Mint a presigned POST for a feedback screenshot (spec §25.4).
Body: ``{filename, content_type, size_bytes?}``. Returns the standard file
envelope plus ``upload_url`` + ``upload_url_fields`` + ``upload_url_method``
(POST — the multipart form is what carries the ``content-length-range``
policy). The client posts the bytes straight to S3, calls
``POST /v1/feedback/screenshots/{id}:commit`` below to flip the row to
``available``, and then passes the id as ``screenshot_file_id`` on
``POST /v1/feedback``.
Ordering is ``submit_feedback``''s, because it is the same dependency: the
share-link refusal, the workspace resolution and the hourly cap all run in
``require_screenshot_presign_context`` — before the body is validated, which
is what makes the cap count malformed requests too.
The ``org_id`` the row is stamped with is the one the dependency RESOLVED,
not ``principal.org_id``. ``?org_id=`` hints are honored here as everywhere
on this router, so the principal''s org is the cookie''s possibly-stale active
workspace; stamping from it would file the object under one org while the
request ran scoped to another.'
operationId: presign_feedback_screenshot_v1_feedback_screenshots_presign_post
parameters:
- name: org_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
title: Org Id
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
- 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/CreateFeedbackScreenshotUploadRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Presign Feedback Screenshot V1 Feedback Screenshots Presign Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/feedback/screenshots/{file_id}:commit:
post:
tags:
- Feedback
summary: Commit Feedback Screenshot
description: 'Finalize a feedback screenshot upload (spec §25.4, NOV-442 review F1).
The screenshot''s own commit rather than the shared ``POST
/v1/files/{id}:commit``, because the two legs of one chain have to agree
about which workspace they are in. The presign resolves ``?org_id=`` and
stamps the row with the SELECTED workspace; the shared route resolves its
org from ``principal.org_id``, which for a browser session is the cookie''s
possibly-stale active org. For a multi-workspace user those differ, and the
chain died at this step — presign 201 in B, commit 404 in A, the row left
``pending`` forever with its object orphaned in S3. Mounting the commit on
``/v1/feedback/*`` puts it behind the same resolution as its siblings, so
the disagreement cannot arise.
The alternative — teaching the shared route to take the hint — was
deliberately not taken: it would extend ``?org_id=`` workspace selection
over the entire file surface to fix one route. This one accepts the hint
only for rows the feedback presign minted (anything else is a 404, in
:func:`app.services.files.commit_feedback_screenshot_for_principal`).
Rate limit: its own ``feedback_upload_commit`` per-user window — see
``require_screenshot_commit_context`` for why it is a third key rather than
a second charge against the presign''s.
Past_due: this path is the §25.4 carve-out from the §18.8 write-block, and
since NOV-442''s review it is the ONLY commit path that carries one. The
shared route went back to being blocked for every producer, screenshots
included — a read-only workspace finishes its screenshot here.'
operationId: commit_feedback_screenshot_v1_feedback_screenshots__file_id__commit_post
parameters:
- name: file_id
in: path
required: true
schema:
type: string
format: uuid
title: File Id
- name: org_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
title: Org Id
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
- 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 Commit Feedback Screenshot V1 Feedback Screenshots File Id Commit Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
/v1/feedback/{feedback_id}:
get:
tags:
- Feedback
summary: Get Own Feedback
description: One of the caller's own submissions. Someone else's → 404, never 403.
operationId: get_own_feedback_v1_feedback__feedback_id__get
parameters:
- name: feedback_id
in: path
required: true
schema:
type: string
format: uuid
title: Feedback Id
- name: org_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
title: Org Id
description: The workspace this call acts in. Browser sessions may name any org the user is a live member of; integration tokens stay pinned to their own.
- 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/FeedbackResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- IntegrationToken: []
components:
schemas:
CreateFeedbackRequest:
properties:
type:
type: string
title: Type
route:
type: string
title: Route
content:
anyOf:
- type: string
- type: 'null'
title: Content
expected:
anyOf:
- type: string
- type: 'null'
title: Expected
severity:
anyOf:
- type: string
- type: 'null'
title: Severity
category:
anyOf:
- type: string
- type: 'null'
title: Category
exit_reason:
anyOf:
- type: string
- type: 'null'
title: Exit Reason
rating:
anyOf:
- type: integer
- type: 'null'
title: Rating
board_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Board Id
card_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Card Id
automation_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Automation Run Id
context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Context
screenshot_file_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Screenshot File Id
app_version:
anyOf:
- type: string
- type: 'null'
title: App Version
additionalProperties: false
type: object
required:
- type
- route
title: CreateFeedbackRequest
description: Body for ``POST /v1/feedback`` (spec §25.4).
CreateFeedbackScreenshotUploadRequest:
properties:
filename:
type: string
maxLength: 255
minLength: 1
title: Filename
content_type:
type: string
maxLength: 255
minLength: 1
title: Content Type
size_bytes:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Size Bytes
additionalProperties: false
type: object
required:
- filename
- content_type
title: CreateFeedbackScreenshotUploadRequest
description: 'Body for ``POST /v1/feedback/screenshots:presign`` (NOV-442, spec §25.4).
Deliberately NOT a reuse of
:class:`~app.schemas.file.CreateFileUploadRequest`: that one requires a
``card_id``, and a feedback screenshot is card-less by construction. The
three fields it does share carry the same wire meaning and the same column
widths.
No ``org_id`` — the org comes from the principal (§25.10). ``content_type``
is a plain ``str`` rather than a ``Literal`` of the four allowed types for
the same reason the submission body keeps its enums loose: the allow-list
lives in :func:`app.services.files._validate_screenshot_content_type`, which
answers ``415 unsupported_content_type`` — the §13.1 shape for a rejected
upload type — where a Literal would answer 422 and split the rule across two
layers. ``size_bytes`` is a hint: the real ceiling is the
``content-length-range`` in the S3 policy, which the client cannot lie past.'
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
FeedbackResponse:
properties:
object:
type: string
title: Object
default: feedback
id:
type: string
format: uuid
title: Id
reference:
type: string
title: Reference
type:
type: string
title: Type
status:
type: string
title: Status
surface:
type: string
title: Surface
severity:
anyOf:
- type: string
- type: 'null'
title: Severity
category:
anyOf:
- type: string
- type: 'null'
title: Category
exit_reason:
anyOf:
- type: string
- type: 'null'
title: Exit Reason
rating:
anyOf:
- type: integer
- type: 'null'
title: Rating
content:
anyOf:
- type: string
- type: 'null'
title: Content
expected:
anyOf:
- type: string
- type: 'null'
title: Expected
board_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Board Id
card_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Card Id
automation_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Automation Run Id
route:
type: string
title: Route
screenshot_file_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Screenshot File Id
app_version:
anyOf:
- type: string
- type: 'null'
title: App Version
api_version:
anyOf:
- type: string
- type: 'null'
title: Api Version
created_time:
type: string
format: date-time
title: Created Time
additionalProperties: false
type: object
required:
- id
- reference
- type
- status
- surface
- route
- created_time
title: FeedbackResponse
description: 'One feedback row as its submitter sees it (spec §25.4).
``org_id`` / ``user_id`` are omitted for the same reason
:class:`~app.schemas.notification.NotificationResponse` omits them: the
caller IS the owner, so echoing the ownership keys back adds nothing and
only widens the surface.
**No ``jira_*`` field at all.** Not the issue key or URL (§25.9: the user
never sees an internal issue id — it leaks backlog structure and means
nothing to a customer), not ``jira_last_error`` (platform-admin-only,
§25.10), and — since NOV-443 — not ``jira_status`` either. A submitter has
no use for the state of an integration they cannot see, and every value it
can take is either uninformative or actively misleading: ``pending`` reads
as "not dealt with yet", ``skipped`` and ``failed`` describe OUR
misconfiguration and OUR outage as though they were something that happened
to the report. The report is durable in either case (§25.6), which is the
only fact the submitter needs, and the ``FB-`` reference is how they quote
it. The ``jira_*`` columns belong to the §25.7 admin schemas.
``context`` is likewise withheld — it is scrubbed diagnostic state for an
operator, and re-serving it would hand a client back the server-side
snapshot (plan, seat counts) it never supplied.'
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).'