Notes API

The Notes API allows the Site Notes to be queried, created, modified and deleted.

HTML Method	URI	Action
GET	/sites/{SITE_ID}/notes	Get Site Notes
POST	/sites/{SITE_ID}/notes	Create Site Notes
PUT	/sites/{SITE_ID}/notes	Modify Site Notes
DELETE	/sites/{SITE_ID}/notes	Delete Site Notes

Get Site Notes

URI Parameters: SITE_ID

Additional Optional URI Parameters:

Parameter	Type	Description	Example
startTime	ISO 8601	First Note time will be >= Date/Time	2019-06-30T22:00:00+10:00
endTime	ISO 8601	Last Note time will be < Date/Time	2020-12-01T08:30:00+10:00
limit	Integer	Maximum number of Notes to return	10
order	String	Time order to return (Asc or Desc) [1]	Desc
timezone	String	Timezone to return time values in [2]	Australia/Sydney
type	String	The types of Notes to return (see below)	user\|button\|survey

[1]	“Asc” for Ascending order , “Desc” for Descending order. Default is “Asc”

[2]	Defaults to the Site’s timezone. If the startTime or endTime parameters do not explicitly include a timezone then this timezone will be used when interpreting those values. “/” character must be encoded as %2F.

Note Types:

Type	Description
all	All types of Notes
user	Notes manually created by a user
button	Notes created when a user interacts with a button on a graph or mimic panel
system	Notes automatically generated by the system
survey	Notes created when a Cathodic Protection Agent uploads survey samples
scheduler	Notes created when a user makes a change in the scheduler UI

Multiple types can be specified using | as a seperator, e.g. user|system

Parameter Examples:

/sites/1000/notes?startTime=2019-01-01T00:00:00Z&limit=500&order=Asc&timezone=Australia%2FAdelaide&type=user

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' 'https://www.telemetry.net.au/api/v1/sites/1000/notes?startTime=2019-01-01T00:00:00Z&limit=20'

Returns: If the call succeeds, returns the Site Notes in JSON format as follows.

{
        "noteCount":2,
        "notes":
        [
                {
                        "id":"1234",
                        "time":"2019-12-01T17:17:40+10:00",
                        "note":"Technician on site",
                        "createdBy":"John Smith",
                        "type":"user"
                },
                {
                        "id":"1235",
                        "time":"2019-12-10T13:13:00+10:00",
                        "note":"Alarms Turned on",
                        "createdBy":"John Smith",
                        "type":"button"
                }
        ]
}

Field	Description
id	Internal unique identifier for the Note
time	Time when the Note was created
note	The body text of the Note
createdBy	The name of the User that created the Note
type	The type of the Note as specified above

Create Site Notes

URI Parameters: SITE_ID

HTML Method: POST

POST Data: JSON format specifying the Notes to create. The format should follow the description above however the only valid fields in the Notes array are “time” and “note”. If “time” timestamp is not specified then the current time is used when creating the Note. The type of Note created is always “user”

Example:

curl -X POST -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' --data '{"notes":[{"time":"2019-12-10T17:17:40+10:00", "note":"test1"},{"note":"test2"}]}' https://www.telemetry.net.au/api/v1/sites/1000/notes

Returns: If the call succeeds, returns the created Notes in JSON format.

Note

API Key must have write access

Modify Site Notes

URI Parameters: SITE_ID

HTML Method: PUT

PUT Data: JSON format specifying the fields to change for the specified Notes. The “id” field must specify the id of the Note to modify, the only other valid fields are “time” and “note”.

Example:

curl -X PUT -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' --data '{"notes":[{"id":"156627", "time":"2019-12-10T18:17:40+10:00", "note":"test3"},{"id":"156628", "note":"test4"}]}' https://www.telemetry.net.au/api/v1/sites/1000/notes

Returns: If the call succeeds, returns the modified notes in JSON format.

Note

API Key must have write access

Delete Site Notes

URI Parameters: SITE_ID

ids: The Note IDs to delete.

HTML Method: DELETE

Example:

curl -X DELETE -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' https://www.telemetry.net.au/api/v1/sites/1000/notes?ids=1234,1235

Returns: If the call succeeds, returns the deleted Notes in JSON format.

Note

API Key must have write access