Sensei API

An API for storing and querying data about one’s coding habits and patterns

Version: 0.33.0

/api/flows/{user}/{ref}

GET

Summary

Query flows

Parameters

Name	Located in	Description	Required	Schema
user	path	User to query flows for	Yes	string
ref	path	A ‘reference’ expression denoting the event to retrieve	Yes	string

Responses

Code	Description	Schema
200		Event
404	`user` or `ref` not found

/api/flows/{user}/latest/timestamp

PATCH

Summary

Changes the latest recorded flow’s start time by some amount of time. If the resulting timestamp happens before the previous flow’s start time, it raises an error. Returns the updated Flow.

Parameters

Name	Located in	Description	Required	Schema
user	path	User to patch latest flow timestamp	Yes	string
body	body		Yes	TimeDifference

Responses

Code	Description	Schema
200		Event
400	Invalid `body`
404	`user` not found

/api/flows/{user}/summary

GET

Summary

Retrieve flows summary, eg. time spend in flows by type, for a given time period. The time period is given by query arguments from and to, with from being inclusive lower bound and to being exclusive upper bound. from must be a valid ISO8601 date before to.

Parameters

Name	Located in	Description	Required	Schema
user	path	User to get summary for	Yes	string
from	query	Starting date (in ISO8601 format) for period summary	No	date
to	query	End date (in ISO8601 format) for period summary	No	date
period	query	Granularity of summary period, to provide meaningful links to next and previous summaries.	No	string

Responses

Code	Description	Schema
200		FlowSummary
400	Invalid `period` or `to` or `from`
404	`user` not found

/api/flows/{user}/{day}/notes

GET

Summary

Retrieve timestamped notes for some day, or all notes if no day is given.

Parameters

Name	Located in	Description	Required	Schema
user	path	User to get notes for	Yes	string
day	path	The date to retrieve notes for, in ISO8601 format.	Yes	date

Responses

Code	Description	Schema
200		[ NoteView ]
404	`user` or `day` not found

/api/flows/{user}/{day}/commands

GET

Summary

Retrieve sequence of executed commands for some day.

Parameters

Name	Located in	Description	Required	Schema
user	path	User to retrieve commands for	Yes	string
day	path	The date to retrieve commands, in ISO8601 format	Yes	date

Responses

Code	Description	Schema
200		[ CommandView ]
404	`user` or `day` not found

/api/flows/{user}/{day}

GET

Summary

Retrieve timeline of flows for a given day.

Parameters

Name	Located in	Description	Required	Schema
user	path	User name to query timeline for	Yes	string
day	path	The date to retrieve flows timeline, in ISO8601 format	Yes	date

Responses

Code	Description	Schema
200		[ FlowView ]
404	`user` or `day` not found

/api/flows/{user}

GET

Summary

Retrieve timeline of flows, grouped by some time slice (Day, Week, Month…). If no ‘group’ param is given, returns all flows.

Parameters

Name	Located in	Description	Required	Schema
user	path	User name to query timeline for	Yes	string
group	query	The periods to group summary. There may be several of them in which case the views will be grouped hierarchically (WIP)	No	[ string ]

Responses

Code	Description	Schema
200		[ GroupViews ]
400	Invalid `group`
404	`user` not found

/api/notes/{user}

GET

Summary

Run a full-text search on all notes, retrieving matching notes.

Parameters

Name	Located in	Description	Required	Schema
user	path	User to search notes for	Yes	string
search	query	The search ‘expression’, ie. some word or sentence fragment	No	string

Responses

Code	Description	Schema
200		[ NoteView ]
400	Invalid `search`
404	`user` not found

/api/log

POST

Summary

Record a new Event in the log.

Parameters

Name	Located in	Description	Required	Schema
body	body		Yes	[ Event ]

Responses

Code	Description	Schema
200		[ ]
400	Invalid `body`

/api/log/{user}

GET

Summary

Retrieve the complete log of all events pertaining to a given user, most recent first

Parameters

Name	Located in	Description	Required	Schema
user	path	User to retrieve log of events for	Yes	string
page	query	Pagination parameter for retrieving events. Events are returned 50 by 50, most recent event first. The ‘next’ and ‘prev’ pages URLs are provided as ‘Link’ header	No	integer

Responses

Code	Description	Schema
200		[ Event ]
400	Invalid `page`
404	`user` not found

/api/users/{user}/token

GET

Summary

Retrieve a fresh signed JWT token for given user.

Parameters

Name	Located in	Description	Required	Schema
user	path	The user to retrieve a token for	Yes	string

Responses

Code	Description	Schema
200		SerializedToken
404	`user` not found

/api/users/{user}

GET

Summary

Retrieve a user’s profile.

Parameters

Name	Located in	Description	Required	Schema
user	path	The user to get profile of	Yes	string

Responses

Code	Description	Schema
200		UserProfile
404	`user` not found

PUT

Summary

Define a user’s profile. If the user does not exist, it is registered

Parameters

Name	Located in	Description	Required	Schema
user	path	User to set profile of	Yes	string
body	body		Yes	UserProfile

Responses

Code	Description	Schema
200		Hex
400	Invalid `body`
404	`user` not found

/api/versions

GET

Summary

Get the server executable and storage versions

Responses

Code	Description	Schema
200		Versions

Models

Event

Name	Type	Required
EventFlow	Flow	No
EventTrace	Trace	No
EventNote	NoteFlow	No

Flow

Name	Type	Required
_flowType	FlowType	Yes
_flowUser	string	Yes
_flowTimestamp	UTCTime	Yes
_flowDir	string	Yes

FlowType

Name	Type	Description	Required
FlowType	string

UTCTime

Name	Type	Description	Required
UTCTime	string

Example

2016-07-22T00:00:00Z

Trace

Name	Type	Required
_traceUser	string	Yes
_traceTimestamp	UTCTime	Yes
_traceDirectory	string	Yes
_traceProcess	string	Yes
_traceArgs	[ string ]	Yes
_traceExitCode	integer	Yes
_traceElapsed	number	Yes

NoteFlow

Name	Type	Required
_noteUser	string	Yes
_noteTimestamp	UTCTime	Yes
_noteDir	string	Yes
_noteContent	string	Yes

TimeDifference

A time difference, positive or negative, expressed as a number of seconds

Name	Type	Description	Required
TimeDifference	number	A time difference, positive or negative, expressed as a number of seconds

FlowSummary

Name	Type	Required
summaryPeriod	[ ]	Yes
summaryFlows	[ [ ] ]	Yes
summaryCommands	[ [ ] ]	Yes

LocalTime

Name	Type	Description	Required
LocalTime	string

Example

2016-07-22T07:40:00

NoteView

Name	Type	Description	Required
noteStart	LocalTime		Yes
noteView	string		Yes

CommandView

Name	Type	Required
commandStart	LocalTime	Yes
commandProcess	string	Yes
commandElapsed	number	Yes

FlowView

Name	Type	Required
flowStart	LocalTime	Yes
flowEnd	LocalTime	Yes
viewType	FlowType	Yes

GroupViews

Name	Type	Description	Required
NoViews	[ ]	Example: `[]`	No
Leaf	FlowView		No
GroupLevel	object		No

Group

Name	Type	Description	Required
Group	string

SerializedToken

A JWT Token in its serialized form, eg. 3 sequneces of base64-encoded strings separated by dots which contain JSON objects. See https://jwt.io/introduction for more details.

Name	Type	Description	Required
SerializedToken	string	A JWT Token in its serialized form, eg. 3 sequneces of base64-encoded strings separated by dots which contain JSON objects. See https://jwt.io/introduction for more details.

UserProfile

Name	Type	Required
userName	string	Yes
userTimezone	TimeZone	Yes
userStartOfDay	TimeOfDay	Yes
userEndOfDay	TimeOfDay	Yes
userFlowTypes	object	No
userCommands	object	No
userPassword	[ ]	Yes

TimeZone

Name	Type	Description	Required
TimeZone	string

TimeOfDay

Name	Type	Description	Required
TimeOfDay	string

Example

12:33:15

Color

An RGB color represented as an hexadecimal string

Name	Type	Description	Required
Color	string	An RGB color represented as an hexadecimal string

Base64

A base64-encoded bytestring.

Name	Type	Description	Required
Base64	string	A base64-encoded bytestring.

Hex

A hex-encoded bytestring.

Name	Type	Description	Required
Hex	string	A hex-encoded bytestring.

Versions

Name	Type	Required
serverVersion	string	Yes
clientVersion	string	Yes
serverStorageVersion	integer	Yes
clientStorageVersion	integer	Yes