HTTP API reference

The HTTP API is a REST-style JSON API for reading and changing sites, layouts and devices, querying history, managing Push API subscriptions and running installation tools. Its OpenAPI description is generated from the code, so it is always complete; this page summarises it.

Conventions

Account and site. Most endpoints take Account and Site as query parameters (or account and site in the request body). Both are required, because a site ID is unique only within its account.

Device IDs. Devices are identified by their device ID, the serial number on the label. List parameters such as Devices are repeated in the query string: Devices=1234567&Devices=7654321. Leaving them out usually means “all devices you may access”, which can be a large response.

Live endpoints. A few endpoints, marked live below, read directly from the running site. Call them on the site’s node, found with GET /realtime/domain, not on api.noccela.io. Calling the wrong node, or a site that is offline, ends in a timeout.

Status codes.

Code	Meaning
200 OK	Data returned
204 No Content	Change accepted, nothing to return
400 Bad Request	The request is invalid; the body explains why where possible
403 Forbidden	The token is missing, expired, or lacks the permission for this site
404 Not Found	Unknown endpoint, or the requested data does not exist
5xx	Server error

Error bodies use the standard ProblemDetails JSON format.

A first request. GET /info returns your app’s client ID and the sites it may access:

curl -s https://api.noccela.io/info -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Endpoints

The groups below follow the tags of the OpenAPI description. “Base station” is called beacon or sensor in endpoint names.

Device information

Method	Path	Purpose
GET	/device	Information about devices (base stations and tags); pass device IDs or leave empty for all
GET	/device/initialtagstate	Current state of tags, as JSON or, with CompactResponse=true, MessagePack (live)
GET	/device/initialbeaconstate	Current state of base stations (live)
GET	/device/neighbors	Base station connections and the signal characteristics of their neighbours (live)

Device modification

Method	Path	Purpose
POST	/device/tag	Change a tag’s properties, such as its name
POST	/device/buzzer	Make tags blink their LED and play the quiet buzzer or the loud alert
POST	/device/addexternaltag	Add an external tag, whose position you supply; returns its device ID (up to 1,000 per account)
POST	/device/modifyexternaltag	Set an external tag’s position, floor, name or button state
POST	/device/removeexternaltag	Remove an external tag
POST	/device/reboot	Reboot base stations
POST	/device/radiostatus	Switch the UWB radio of base stations on or off

General information

Method	Path	Purpose
GET	/info	Your app’s client ID and its permissions per site; a good connection test

History

Method	Path	Purpose
GET	/history	Stored positions and states of tags in a time span
GET	/history/socialdistancing	Stored proximity (contact) events between tags

GET /history needs a Start time or a Count. Start and Stop take ISO 8601 dates or times (the default span is the last 24 hours); Count returns the latest N rows per tag; IncludeProperties limits the fields returned; Timeout sets the database timeout in seconds (default 30). History stores a new row only when a tag has moved more than 0.5 m.

curl -s -G https://api.noccela.io/history \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "Account=YOUR_ACCOUNT_ID" \
  --data-urlencode "Site=YOUR_SITE_ID" \
  --data-urlencode "Devices=1234567" \
  --data-urlencode "Start=2026-10-21T06:00:00Z" \
  --data-urlencode "Stop=2026-10-21T14:00:00Z"

Event API (Push API)

Used to set up the Push API.

Method	Path	Purpose
POST	/eventapi/endpoint	Create an endpoint: your HTTPS URL that will receive events
GET	/eventapi/endpoint	Details of one or more endpoints; all of yours if no ID is given
DELETE	/eventapi/endpoint	Remove an endpoint and all its subscriptions
POST	/eventapi/registerendpoint	Validate an endpoint; Noccela sends it a challenge request
POST	/eventapi/modifyendpoint	Change an endpoint’s retry policy or secret
POST	/eventapi/event	Subscribe an endpoint to an event type
GET	/eventapi/event	List subscriptions, by subscription ID or by endpoint
DELETE	/eventapi/event	Remove a subscription
GET	/eventapi/events	Fetch the stored events of a subscription, after a given event ID

Installation tool

Planning and automatic calibration of base stations.

Method	Path	Purpose
POST	/installationtool/sensorlocationsuggestion	Suggested base station positions for an area, use case and difficulty
POST	/installationtool/calibratepositions	Calibrated base station positions from their ranging data and reference points
POST	/installationtool/beaconled	Change a base station’s LED colour for a few seconds, to check its identity on site
GET	/installationtool/gettagpoints	List the site’s tag points (reference points measured with a tag)
POST	/installationtool/addtagpoint	Add a tag point and start collecting data for it
POST	/installationtool/updatetagpoint	Update a tag point and collect data again
POST	/installationtool/removetagpoint	Remove a tag point
POST	/installationtool/maptagpoints	Map tag points for calibration

Integrations

Manage apps and their credentials programmatically, as in the partner portal.

Method	Path	Purpose
GET	/integrations/list	List your apps
GET	/integrations/get	Details of one app
POST	/integrations/create	Create an app with a name, description and permissions
POST	/integrations/modify	Change an app
DELETE	/integrations/delete	Delete an app
GET	/integrations/secrets	List an app’s client secrets (metadata, not the secrets)
POST	/integrations/secret	Create a new client secret
DELETE	/integrations/deletesecret	Delete a client secret

Network

Method	Path	Purpose
GET	/network/settings	Network settings available for editing
POST	/network/settings	Change network settings; fetch the current ones first

Real time

Method	Path	Purpose
GET	/realtime/domain	The node that runs a site; connect the real-time API there
GET	/realtime	WebSocket entry point; see the real-time API. It answers 101 Switching Protocols and cannot be tried in Swagger UI

Site information

Method	Path	Purpose
GET	/site	Basic site information, including its name and location
GET	/site/layout	The site layout: walls, areas, base station positions; optionally an older version by MinorId
GET	/site/layout/versions	All layout versions, for viewing or restoring
GET	/site/settings	Site settings available for editing
GET	/site/availablesensors	Base stations assigned to the account but not to another site
GET	/site/sensorlocations	Base station coordinates relative to the site’s origin
GET	/site/blueprint	Information about the site’s floor-plan images
GET	/site/file	Download a site file, such as a floor plan, by its file ID

Site modification

Method	Path	Purpose
POST	/site/layout	Save a new layout: infrastructure, walls, alert areas. Replaces the whole layout
DELETE	/site/layout	Delete a layout version (not the active one)
POST	/site/layout/activate	Activate an earlier layout version
POST	/site/layout/modify	Change a layout version’s properties
POST	/site/layout/fillpolygon	Fill a polygon with smaller, non-overlapping polygons
POST	/site/settings	Change site settings; fetch the current ones first
POST	/site/sensorlocations	Set base station coordinates; base stations missing from the request are removed
POST	/site/reload	Reload the site in the cloud so that changes such as layout edits take effect
POST	/site/usecaseanddifficulty	Set the site’s use case and environment difficulty
POST	/site/create	Create a site (needs the account’s “all sites” permission)
DELETE	/site/remove	Remove a site (needs the account’s “all sites” permission)

Some changes, such as layout edits and base station positions, take effect only after a reload. If you make several changes, reload once at the end.

Workflows

Method	Path	Purpose
GET	/workflow/getworkflows	The workflows defined on a site
GET	/workflow/getworkflowresults	Results of a workflow
POST	/workflow/externaltrigger	Trigger workflow steps whose condition is “external trigger”, for all or selected tags

Generate a client

Noccela does not ship HTTP client libraries; generate one from the OpenAPI description instead, so it always matches the API version you target. For example, with OpenAPI Generator:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.noccela.io/swagger/v1/swagger.json \
  -g typescript-fetch \
  -o ./noccela-client

Generators exist for most languages: Python, Java, C#, Go and others.

Try it in Swagger UI

Open Swagger UI, select Authorize, and enter your client ID and secret. You do not need to tick the global scope; every client has it. Then choose an endpoint, select Try it out, fill in the parameters and select Execute.