API
The camera application serves a small JSON API at https://<camera>/local/raviden/api/. The web interface uses it, and everything the interface shows or saves is available through it. An engineer, a script or an AI assistant can read the live status, change the configuration and pull a support bundle without opening the interface.
Access
| Item | Details |
|---|---|
| Base path | https://<camera>/local/raviden/api/ |
| Login | The camera's own administrator account, with HTTP digest or basic authentication. Any other account gets 401. |
| Transport | HTTPS only. The camera's certificate is self-signed unless the plant installed one. |
| Format | Every response is JSON. Errors carry {"error": "<reason>"} and an HTTP status. |
An assistant that drives the API holds the camera's administrator login. Give it a dedicated account and remove it afterwards.
curl -sk --anyauth -u admin:password https://192.168.0.200/local/raviden/api/status
Configuration
The configuration is one JSON document with five sections: connections, tags, overlay, streamEncode and settings. There are no routes for single connections, tags or elements. A change reads the document, edits it and writes the whole document back. The camera validates it against the configuration schema, applies it live and does not restart.
| Route | Method | Returns |
|---|---|---|
/config | GET | The current configuration. Connection passwords are blank. |
/config?base=N | PUT | {"ok": true} after the camera validates and applies the document. 422 with the reason when it is refused, 409 on conflict. |
/schema | GET | The JSON schema the camera validates against. Also served on this site at /schema/config.schema.json. |
A blank password in a PUT keeps the password already stored for that connection id, so you can write a document read from GET back unchanged.
Procedure
- Status. Read
/statusand noteconfigUserGeneration, the generation of the last save made by a person. - Document. Read
/configand make the change. - Write. PUT the document with
baseset to the generation from step 1. The camera answers409if someone saved in between. Read again and repeat rather than addingforce=1. That flag overwrites the other save. - Check. Read
/statusagain. A tag added in the document appears with a value once its connection reads it.
Status
| Route | Method | Returns |
|---|---|---|
/status | GET | Every connection and every tag, keyed by id, plus the three generation counters and the live DataBorder estimates when the DataBorder is on. |
/events | GET | The same document as a server-sent event named status, pushed whenever a value, quality or connection state changes. |
| Field | On | Values |
|---|---|---|
state | connection | disabled, connecting, connected or error |
lastError, lastOkMs | connection | The reason for the last failure and the time of the last successful read, in milliseconds. |
value, tsMs | tag | The last value and when it was read. |
quality | tag | good, bad or uninit for a tag that has never been read. |
reads, errors, lastError | tag | Counters since the application started and the text of the last failed read. |
The camera polls only used tags. A tag that is on no overlay element, not in the DataBorder and not feeding a derived state stays uninit.
History
| Route | Method | Returns |
|---|---|---|
/history | GET | The stored-data summary: the tiers, each tag's fill, the oldest sample, memory and flash use, and the last save to flash. |
/history/<tag>?window=<s> | GET | One tag's history over the window, in seconds. Default 3600, minimum 60, maximum 604800. |
The reply's kind says which shape follows. A measurement tag returns buckets, each with t, min, max, last, avg and n, at the finest tier that covers the window. A state tag returns runs, totals, hourly and current. A string tag returns entries of t and v. Gaps are absent rather than filled.
Tag browsing
| Route | Method | Returns |
|---|---|---|
/browse/<connection> | GET | The tags the connection's source offers, each with name, scope, dataType, scalar and, for a structure, udtId. |
/browse/<connection>/udt/<id> | GET | The members of one Allen-Bradley user-defined type. |
Browsing opens its own session to the source, so the connection does not need to be enabled. 404 names an unknown connection id and 502 carries the source's refusal.
Support and identity
| Route | Method | Returns |
|---|---|---|
/about | GET | The application name, version, build time and build commit. |
/diagnostics | GET | The support bundle: build, camera model and firmware, the application's log lines, the live status, the configuration with passwords blank, and the health counters. |
/appstats | GET | One raw sample of the health counters. Rates and CPU shares come from the difference between two samples. |
/signing-key | GET | The DataBorder's Ed25519 public key and its fingerprint. See Verification. |
The diagnostics bundle is the same file as Settings → Config file → Download diagnostics. It contains nothing secret and is the first thing to hand to support or to an assistant.
Backup and restore
| Route | Method | Returns |
|---|---|---|
/backup | GET | The configuration with passwords blank and the stored history, as one bundle. |
/backup?secrets=1 | GET | The same bundle plus the connection passwords and the private signing key. The bundle's secrets field is true. |
/restore | POST | Writes a bundle to the camera and restarts the application. {"ok": true, "written": N} on success, 400 naming the bad entry otherwise. |
A bundle with secrets is the only way to move a camera's identity. Recordings verify against the signing key, and a new key gives a new fingerprint. Keep such a bundle off shared drives and out of chat transcripts. A restore from a bundle without secrets keeps the camera's existing key and passwords, or generates a key on a fresh install.