NovumOS Beacon API

The beacon API from NovumOS — 4 operation(s) for beacon.

GitHub OpenAPI

Operations 4

POST /v1/beacon Post Beacon #
POST /v1/beacon/snapshot Post Snapshot #
POST /v1/beacon/replay Post Replay #
GET /v1/beacon/config Get Beacon Config #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/novumos-app:novumos-app-beacon-api"
All apis
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.

Get an API 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 Specification

novumos-app-beacon-api-openapi.yml Raw ↑
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).'