API

Reading and writing the camera application over HTTP.

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

ItemDetails
Base pathhttps://<camera>/local/raviden/api/
LoginThe camera's own administrator account, with HTTP digest or basic authentication. Any other account gets 401.
TransportHTTPS only. The camera's certificate is self-signed unless the plant installed one.
FormatEvery 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.

RouteMethodReturns
/configGETThe current configuration. Connection passwords are blank.
/config?base=NPUT{"ok": true} after the camera validates and applies the document. 422 with the reason when it is refused, 409 on conflict.
/schemaGETThe 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

  1. Status. Read /status and note configUserGeneration, the generation of the last save made by a person.
  2. Document. Read /config and make the change.
  3. Write. PUT the document with base set to the generation from step 1. The camera answers 409 if someone saved in between. Read again and repeat rather than adding force=1. That flag overwrites the other save.
  4. Check. Read /status again. A tag added in the document appears with a value once its connection reads it.

Status

RouteMethodReturns
/statusGETEvery connection and every tag, keyed by id, plus the three generation counters and the live DataBorder estimates when the DataBorder is on.
/eventsGETThe same document as a server-sent event named status, pushed whenever a value, quality or connection state changes.
FieldOnValues
stateconnectiondisabled, connecting, connected or error
lastError, lastOkMsconnectionThe reason for the last failure and the time of the last successful read, in milliseconds.
value, tsMstagThe last value and when it was read.
qualitytaggood, bad or uninit for a tag that has never been read.
reads, errors, lastErrortagCounters 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

RouteMethodReturns
/historyGETThe 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>GETOne 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

RouteMethodReturns
/browse/<connection>GETThe tags the connection's source offers, each with name, scope, dataType, scalar and, for a structure, udtId.
/browse/<connection>/udt/<id>GETThe 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

RouteMethodReturns
/aboutGETThe application name, version, build time and build commit.
/diagnosticsGETThe support bundle: build, camera model and firmware, the application's log lines, the live status, the configuration with passwords blank, and the health counters.
/appstatsGETOne raw sample of the health counters. Rates and CPU shares come from the difference between two samples.
/signing-keyGETThe 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

RouteMethodReturns
/backupGETThe configuration with passwords blank and the stored history, as one bundle.
/backup?secrets=1GETThe same bundle plus the connection passwords and the private signing key. The bundle's secrets field is true.
/restorePOSTWrites 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.