NovumOS Beacon API
The beacon API from NovumOS — 4 operation(s) for beacon.
The beacon API from NovumOS — 4 operation(s) for beacon.
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-beacon-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 Beacon API
description: Block-based kanban where agents are first-class users.
version: 0.0.0
tags:
- name: beacon
paths:
/v1/beacon:
post:
tags:
- beacon
summary: Post Beacon
description: 'Accept one batch of behavioral events (WIRE-1..6).
Returns 204 on success and on every drop. See the module docstring for why.'
operationId: post_beacon_v1_beacon_post
responses:
'204':
description: Successful Response
/v1/beacon/snapshot:
post:
tags:
- beacon
summary: Post Snapshot
description: 'Accept one masked DOM canvas for a (route × bucket × epoch) (HEAT-2).
The heatmap''s backdrop, not an event: P2c renders stored click coordinates
over this document in a sandboxed iframe, which is why §26 forbids a
screenshot service and asks for a serialized DOM instead.
**The gate order is the same contract as ``post_beacon``**, and the two
deliberately share every helper that implements it — kill switch, then
parse, then property + origin, then principal, then the bot filter, then
identity. What differs is three checks this payload needs and a batch of
events does not:
* **The recording purpose is required** (PRIV-1, REP-2). A DOM snapshot is
replay-class content — it is a serialization of the visitor''s actual
screen — so the aggregate floor does not authorize it, and neither does an
analytics-only grant. This mirrors §26.4''s rule for ``/v1/beacon/replay``
and is the reason the tracker only ever schedules a capture in ``full``
mode: the client gate and this one are two independent readings of the
same requirement, and either alone would be a single point of failure.
* **The declared masking level must meet the property''s** (REP-2). Weaker is
dropped; stronger is accepted, because a client that masked harder than
asked has not violated anything.
* **Route exclusions apply exactly as they do to events** (TRK-8). A route
we promised never to capture must not arrive as a full serialization of
itself, and the exclusion list is server-side truth — a stale tracker that
has not polled the new config yet gets caught here.
**The bot filter has no integration-token exemption here**, unlike the event
beacon. That exemption exists because an agent''s HTTP client legitimately
has a bot-shaped UA and its behavioral events are a segmentation dimension
we want. A DOM snapshot is different in kind: a token-bearing agent has no
DOM to serialize, so a snapshot arriving under one is either a headless
browser in CI or something forged, and either would overwrite the canonical
canvas for a route with markup no human ever saw.
Returns 204 on success and on every drop, exactly like the event beacon —
a differentiated response would turn this route into an oracle for which
properties exist and what they are configured to allow.'
operationId: post_snapshot_v1_beacon_snapshot_post
responses:
'204':
description: Successful Response
/v1/beacon/replay:
post:
tags:
- beacon
summary: Post Replay
description: 'Accept one chunk of one session''s recording (REP-1..6, §26.8).
**The gate order is the same contract as the other two routes**, built out
of the same helpers, and the two checks that differ from the snapshot route
differ because a recording is not a canvas:
* **The property''s replay mode must permit it.** ``off`` means this property
records nothing, and that has to be enforced here and not only in the
tracker — the config endpoint is a request a hand-rolled client can simply
not make. This is the replay analogue of the property gate, and it is the
one control an operator has that takes effect without a deploy.
* **There is no route gate on the payload, only on the chunk''s label.** A
recording crosses routes by construction, so "was this chunk taken on an
excluded route" has no answer — the events inside it may span five. What
the route exclusion means for replay is therefore enforced on the *client*
(the recorder stops when it enters an excluded route) and the label a
chunk arrives with is checked here as a backstop against a stale tracker,
not as a claim about every event inside.
Everything else is deliberately identical to ``post_snapshot``: the recording
purpose is required (PRIV-1, WIRE-4) and checked server-side because the
client gate and this one are two independent readings of one requirement; the
declared masking level must meet the property''s (REP-2); and **the bot filter
grants no integration-token exemption**, because a token-bearing agent has no
DOM to record, so a recording arriving under one is either a headless browser
in CI or something forged.
Chunks are written **server-side** to S3 rather than through §25''s browser
presign-POST handshake, and that is a design decision rather than an
omission: a presigned PUT would put the browser in direct contact with the
bucket, and every gate above — consent, masking, mode, budget — would become
advice the client could decline to take. Passing the bytes through here costs
a hop and keeps enforcement server-visible.
Returns 204 on success and on every drop, like its siblings.'
operationId: post_replay_v1_beacon_replay_post
responses:
'204':
description: Successful Response
/v1/beacon/config:
get:
tags:
- beacon
summary: Get Beacon Config
description: 'Serve one property''s runtime knobs — the tracker''s kill switch (TRK-8).
The query parameter is ``?property=`` because that is what the NOV-615
tracker sends. It resolves against ``BxProperty.key``; ``name`` is a display
label and is never addressable.
An unknown property, a disabled one, and a deployment with ``bx_enabled``
off all return the same well-formed ``enabled: false`` body. That is the
contract the tracker is written against: it must be able to go inert on a
response it can parse, and a 404 for unknown properties would let anyone
enumerate which ones are registered.
``property_key`` is echoed only when the property is actually live. The
tracker treats an absent key as disabled, so nulling it is a second kill
switch that works even if ``enabled`` were somehow misread — and because
"registered but disabled" and "never existed" both answer ``null``, the
field cannot be used to probe which properties exist.
Reads no org-scoped table and takes no principal — the response depends only
on the property, so it is identical for every caller and can never leak
tenant data.'
operationId: get_beacon_config_v1_beacon_config_get
parameters:
- name: property
in: query
required: false
schema:
type: string
maxLength: 64
default: ''
title: Property
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BeaconConfigResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
BeaconConfigResponse:
properties:
object:
type: string
title: Object
default: beacon_config
enabled:
type: boolean
title: Enabled
property_key:
anyOf:
- type: string
- type: 'null'
title: Property Key
sample_rate:
type: number
title: Sample Rate
replay_mode:
type: string
title: Replay Mode
replay_sample_rate:
type: number
title: Replay Sample Rate
default: 0.0
masking_level:
type: string
title: Masking Level
route_exclusions:
items:
type: string
type: array
title: Route Exclusions
flush_interval_ms:
type: integer
title: Flush Interval Ms
max_batch:
type: integer
title: Max Batch
config_poll_s:
type: integer
title: Config Poll S
allow_webdriver:
type: boolean
title: Allow Webdriver
default: false
type: object
required:
- enabled
- sample_rate
- replay_mode
- masking_level
- route_exclusions
- flush_interval_ms
- max_batch
- config_poll_s
title: BeaconConfigResponse
description: '``GET /v1/beacon/config?property=<key>`` — the tracker''s kill switch (TRK-8).
Served for any property, known or not. An unknown or disabled one gets a
well-formed ``enabled: false`` body rather than a 404, for two reasons: a
tracker must be able to go inert on a config it can parse (a 404 would leave
it retrying or, worse, falling back to defaults), and a differentiated
response would turn this route into an oracle for which properties exist.
``property_key`` is echoed back for the tracker to put in its envelopes, and
is ``None`` for anything not actively enabled. The tracker treats an absent
key as disabled, so that nulling is a second, independent kill switch — and
it keeps the anti-oracle property, because "exists but disabled" and "never
existed" produce byte-identical bodies.'
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).'