Labels and notes API

These endpoints manage your triage labels, attach them to events, and write your note on an event. They are the API side of the labels and notes on the events page.

How labels and notes work

A label is a colored tag of your own, such as "triage" or "false positive", that you attach to events to mark them. A note is one piece of free text you keep on an event. Both are private to your account. See Triage for how they look on the events page.

Event ids are numbers that are easy to guess, so the calls that write to an event answer 404, not 403, for an event that exists but is not yours: a foreign id looks exactly like one that does not exist. For the same reason, detaching a label and deleting a note answer 204 whether or not the event was yours, and change nothing when it was not.

Every call here except the list is a write.

List labels

GET /api/event_labels/ lists your labels, by name.

GET /api/event_labels/

{ "labels": [ { "id": 1, "name": "triage", "color": "amber" } ] }

Use a label's id in the labels filter of the events query to list only the events carrying it.

Create a label

POST /api/event_labels/ creates a label and answers 201 with it.

POST /api/event_labels/

JSON body:

curl -s https://eyalsec.com/api/event_labels/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"triage","color":"amber"}'

{ "id": 1, "name": "triage", "color": "amber" }

Rename or recolor a label

PATCH /api/event_labels/{id}/ sets a label's name and color and answers 204.

PATCH /api/event_labels/{id}/

Send name (required) and color. Both are written every time, so leaving color out sets it back to amber. Renaming onto another of your labels' names is a 409, and a label that is not yours is a 404.

curl -s -X PATCH https://eyalsec.com/api/event_labels/1/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"reviewed","color":"green"}'

Delete a label

DELETE /api/event_labels/{id}/ deletes a label and removes it from every event it was on. It answers 204; a label that is not yours is a 404.

DELETE /api/event_labels/{id}/

Attach a label to an event

POST /api/event/{id}/labels/ puts one of your labels on one of your events and answers 204. {id} is the event id, index 7 of an event row.

POST /api/event/{id}/labels/

JSON body: label_id (required). Attaching a label that is already on the event does nothing and is not an error.

curl -s https://eyalsec.com/api/event/12345/labels/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"label_id":1}'

Detach a label from an event

DELETE /api/event/{id}/labels/{labelID}/ takes one label off one event and answers 204. Detaching a label that was not attached does nothing.

DELETE /api/event/{id}/labels/{labelID}/

curl -s -X DELETE https://eyalsec.com/api/event/12345/labels/1/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000"

Write your note on an event

PUT /api/event/{id}/comment/ sets your note on an event and answers 204. You have one note per event; writing again replaces it. See notes.

PUT /api/event/{id}/comment/

JSON body: body (required), at most 4096 bytes.

curl -s -X PUT https://eyalsec.com/api/event/12345/comment/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"body":"looks like a false positive"}'

To read the note back, use one event's detail: its comment field holds the text, and index 14 of the event row says whether a note exists.

Delete your note on an event

DELETE /api/event/{id}/comment/ removes your note from an event and answers 204.

DELETE /api/event/{id}/comment/