SmaCH
SmaCH API
SmaCH API

events

Download schema

Events: what a recording session recorded

Push an event on the monitoring of an artwork

POST
https://api.smach.science
/artworks/{reference}/monitorings/events

Records what happened, on the session the source belongs to. A start moves that session to in progress and the artwork to monitoring; a stop ends it and sends the artwork back to ready. Either one arriving twice is accepted and changes nothing, so a retry never loses the event it carries. An ended session records nothing more.

Push an event on the monitoring of an artwork › path Parameters

reference
​string · minLength: 1 · required

Push an event on the monitoring of an artwork › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Push an event on the monitoring of an artwork › Request Body

Event - what happened during a recording session
Event
type
​string · enum · required

What happened

Enum values:
start
alert
position
notification
stop
severity
​string · enum · required

How much it matters

Enum values:
info
warning
critical
date
​string · date-time · required

When it happened, on the device

​Location · required

Where the device thought it was. The object is required, a fix is not: a position resolved against a cell carries no latitude

sourceType
​string · enum · required

What kind of thing the source names, which decides how the event is routed

Enum values:
monitoring
sensor
logger
user
source
​string · minLength: 1 · required

Who or what reported it: a monitoring id, a sensor or logger identity, or the email of a user

id
​string · uuid · readOnly

Identifier

organization
​string · readOnly

Organization of the monitoring this event was routed to

monitoring
​string · uuid · readOnly

Monitoring this event was routed to

artwork
​string · readOnly

Reference of the monitored artwork

message
​string

Why the threshold was crossed, on an alert

tag
​string

Free annotation carried by a notification

​Coordinate

Rotation of the device on three axes

​Coordinate

Acceleration of the device on three axes

speed
​number · double

Speed of the device, in metres per second

sensor
​Captor · enum

The captor that crossed its threshold, on an alert. Absent when the alert reports the state of the device itself, such as its battery or its storage

Enum values:
accelerometer
temperature
humidity
values
​number[]

What the captor measured: three axes for an accelerometer, one value for a temperature or a humidity

created
​string · date-time · readOnly

When this service received it

Push an event on the monitoring of an artwork › Responses

Recorded

Event - what happened during a recording session
Event
type
​string · enum · required

What happened

Enum values:
start
alert
position
notification
stop
severity
​string · enum · required

How much it matters

Enum values:
info
warning
critical
date
​string · date-time · required

When it happened, on the device

​Location · required

Where the device thought it was. The object is required, a fix is not: a position resolved against a cell carries no latitude

sourceType
​string · enum · required

What kind of thing the source names, which decides how the event is routed

Enum values:
monitoring
sensor
logger
user
source
​string · minLength: 1 · required

Who or what reported it: a monitoring id, a sensor or logger identity, or the email of a user

id
​string · uuid · readOnly

Identifier

organization
​string · readOnly

Organization of the monitoring this event was routed to

monitoring
​string · uuid · readOnly

Monitoring this event was routed to

artwork
​string · readOnly

Reference of the monitored artwork

message
​string

Why the threshold was crossed, on an alert

tag
​string

Free annotation carried by a notification

​Coordinate

Rotation of the device on three axes

​Coordinate

Acceleration of the device on three axes

speed
​number · double

Speed of the device, in metres per second

sensor
​Captor · enum

The captor that crossed its threshold, on an alert. Absent when the alert reports the state of the device itself, such as its battery or its storage

Enum values:
accelerometer
temperature
humidity
values
​number[]

What the captor measured: three axes for an accelerometer, one value for a temperature or a humidity

created
​string · date-time · readOnly

When this service received it

List the events of a monitoring

GET
https://api.smach.science
/monitorings/{id}/events

The timeline of one session, oldest first. Follow the Link header to page through it. The search parameter matches the message of an alert, anywhere in the field. Sortable on date, type, severity, created.

List the events of a monitoring › path Parameters

id
​string · uuid · required

List the events of a monitoring › query Parameters

page
​integer · int32 · min: 0

0-indexed page number

Default: 0
size
​integer · int32 · min: 1 · max: 200

Page size

Default: 50
search
​string

Free-text search. The fields it matches are documented per endpoint.

sort
​string

Sort field, prefixed with '-' for descending (e.g. -createdAt), composed with commas. The sortable fields are documented per endpoint.

type
​string[]

Keep only events of one of these types

Enum values:
start
alert
position
notification
stop
severity
​string[]

Keep only events of one of these severities

Enum values:
info
warning
critical
sourceType
​string · enum

Keep only events reported by that kind of source

What the source names, which decides how the event is routed

Enum values:
monitoring
sensor
logger
user
source
​string

Keep only events reported by that exact source

sensor
​Captor · enum

Keep only alerts raised by that captor

Enum values:
accelerometer
temperature
humidity

List the events of a monitoring › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

List the events of a monitoring › Responses

A page of results

Event - what happened during a recording session
Event
type
​string · enum · required

What happened

Enum values:
start
alert
position
notification
stop
severity
​string · enum · required

How much it matters

Enum values:
info
warning
critical
date
​string · date-time · required

When it happened, on the device

​Location · required

Where the device thought it was. The object is required, a fix is not: a position resolved against a cell carries no latitude

sourceType
​string · enum · required

What kind of thing the source names, which decides how the event is routed

Enum values:
monitoring
sensor
logger
user
source
​string · minLength: 1 · required

Who or what reported it: a monitoring id, a sensor or logger identity, or the email of a user

id
​string · uuid · readOnly

Identifier

organization
​string · readOnly

Organization of the monitoring this event was routed to

monitoring
​string · uuid · readOnly

Monitoring this event was routed to

artwork
​string · readOnly

Reference of the monitored artwork

message
​string

Why the threshold was crossed, on an alert

tag
​string

Free annotation carried by a notification

​Coordinate

Rotation of the device on three axes

​Coordinate

Acceleration of the device on three axes

speed
​number · double

Speed of the device, in metres per second

sensor
​Captor · enum

The captor that crossed its threshold, on an alert. Absent when the alert reports the state of the device itself, such as its battery or its storage

Enum values:
accelerometer
temperature
humidity
values
​number[]

What the captor measured: three axes for an accelerometer, one value for a temperature or a humidity

created
​string · date-time · readOnly

When this service received it

Count what a monitoring recorded

GET
https://api.smach.science
/monitorings/{id}/events/count

Totals per type, and for alerts per severity and per captor. A breakdown carries only the keys the session has; an absent key reads as zero.

Count what a monitoring recorded › path Parameters

id
​string · uuid · required

Count what a monitoring recorded › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Count what a monitoring recorded › Responses

Unknown monitoring id

What a recording session holds, counted
EventCountReport
total
​integer · int64

Total number of events

​object

Count per type: start, alert, position, notification, stop

​object

Count per severity, alerts only: info, warning, critical

​object

Count per captor, alerts only: accelerometer, temperature, humidity

Chart the alerts of a monitoring

GET
https://api.smach.science
/monitorings/{id}/charts

The alerts of one session that name a captor, oldest first, one series per captor, laid out in parallel columns. Values are raw device units. The thresholds to draw are the configuration of the monitoring. Alerts on the battery or the storage are not charted.

Chart the alerts of a monitoring › path Parameters

id
​string · uuid · required

Chart the alerts of a monitoring › query Parameters

from
​string · date-time

Keep alerts dated from this instant, inclusive (ISO 8601)

to
​string · date-time

Keep alerts dated up to this instant, inclusive (ISO 8601)

Chart the alerts of a monitoring › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Chart the alerts of a monitoring › Responses

from is after to, or a bound is not an ISO 8601 instant

The alerts of a monitoring, one series per captor, laid out in columns for a chart
MonitoringCharts
​object

One series per captor that raised an alert. A captor with none is absent

Where the monitorings stand

GET
https://api.smach.science
/monitorings/overview

Monitorings, each with what its events say: when it started and ended, when it last reported, its alerts per severity, its latest alert and its latest position. Without a status, the ones that are set up or recording. Filters, searches, pages and sorts as the monitoring list does. Facts only: how long a silence has to last before it matters is left to the reader, since events are relayed by the mobile application rather than sent by the devices.

Where the monitorings stand › query Parameters

page
​integer · int32 · min: 0

0-indexed page number

Default: 0
size
​integer · int32 · min: 1 · max: 200

Page size

Default: 50
search
​string

Free-text search. The fields it matches are documented per endpoint.

sort
​string

Sort field, prefixed with '-' for descending (e.g. -createdAt), composed with commas. The sortable fields are documented per endpoint.

status
​string[]

Keep only monitorings in one of these statuses; set up or recording when absent

Enum values:
pending
in_progress
ended
type
​string[]

Keep only monitorings of one of these types

Enum values:
stationary
transport

Where the monitorings stand › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Where the monitorings stand › Responses

200

A page of results

A monitoring, with what its events say about it
MonitoringOverview
​Monitoring

The monitoring

started
​string · date-time

When recording started, from the start event. Absent while the monitoring is only set up

ended
​string · date-time

When recording stopped, from the stop event. Absent until the monitoring has ended

lastEvent
​string · date-time

Date of the latest event, as reported by the device. Absent when nothing was recorded

lastReceived
​string · date-time

When this service last received an event of the monitoring. A long gap is not by itself a fault: events are relayed by the mobile application, not sent by the devices

​object

Alerts per severity. A severity with no alert is absent and reads as zero

​Event

The latest alert

​Location

Where the latest position placed it. Transport only

Subscribe to events as they happen

GET
https://api.smach.science
/monitorings/events/stream

Opens a Server-Sent Events stream carrying every event recorded by the organization, whichever session recorded it, in the same JSON form the timeline endpoints return. The stream ends on its own after a while and is meant to be reopened; a browser EventSource does that by itself.

Two things are worth knowing before reading from it. Alerts are rate limited per captor and per session, so a burst arrives as one alert per captor rather than as hundreds; the timeline endpoint is what holds all of them. And a comment line is sent down a quiet stream at regular intervals to keep intermediaries from closing it, which a client never sees as a message.

What reaches a subscriber is what their organization recorded, and nothing else.

Subscribe to events as they happen › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Subscribe to events as they happen › Responses

The stream is open

Event - what happened during a recording session
Event
type
​string · enum · required

What happened

Enum values:
start
alert
position
notification
stop
severity
​string · enum · required

How much it matters

Enum values:
info
warning
critical
date
​string · date-time · required

When it happened, on the device

​Location · required

Where the device thought it was. The object is required, a fix is not: a position resolved against a cell carries no latitude

sourceType
​string · enum · required

What kind of thing the source names, which decides how the event is routed

Enum values:
monitoring
sensor
logger
user
source
​string · minLength: 1 · required

Who or what reported it: a monitoring id, a sensor or logger identity, or the email of a user

id
​string · uuid · readOnly

Identifier

organization
​string · readOnly

Organization of the monitoring this event was routed to

monitoring
​string · uuid · readOnly

Monitoring this event was routed to

artwork
​string · readOnly

Reference of the monitored artwork

message
​string

Why the threshold was crossed, on an alert

tag
​string

Free annotation carried by a notification

​Coordinate

Rotation of the device on three axes

​Coordinate

Acceleration of the device on three axes

speed
​number · double

Speed of the device, in metres per second

sensor
​Captor · enum

The captor that crossed its threshold, on an alert. Absent when the alert reports the state of the device itself, such as its battery or its storage

Enum values:
accelerometer
temperature
humidity
values
​number[]

What the captor measured: three axes for an accelerometer, one value for a temperature or a humidity

created
​string · date-time · readOnly

When this service received it

Delete one recorded event

DELETE
https://api.smach.science
/monitorings/events/{id}

Removes one measurement from a session. A start or a stop is refused: those are the bounds of the session and its status was moved by them.

Delete one recorded event › path Parameters

id
​string · uuid · required

Delete one recorded event › Headers

X-Organization
​string

The organization alias the request applies to, not its display name.

Optional for an account belonging to a single organization, which is resolved from the token. Required beyond that, since no default is defensible. A super-admin may name any organization, or none, which reads across all of them.

Delete one recorded event › Responses

Deleted

No data returned
monitoringsartworks