NAV
JSON

ScreenAware API Docs

Welcome to the ScreenAware API! You can use our API to access the ScreenAware REST API endpoints. See code examples in the dark area to the right.

The base API Endpoint is located at: https://app.screenaware.com/api

Authentication

# On the shell, obtain the bearer token initially
curl --data "email=YOUREMAIL&password=YOURPASSWORD" https://app.screenaware.com/api/auth/local

Example Request JSON Payload:

{
  "email": "youremail@provider.com",
  "password": "mysecretpassword0815"
}

Example JSON Response:

{
  "token": "eyJ0eXAiOiJKV1QiFDJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NWEwMzU2YzVhOTVlOTI0MWJlM2Y0ODUiLCJpYXQiOjE0NDg4MjkyODMsImV4cCI6MTQ0OTA1NTY4M40.4ei1hTEi1VdT4pK8Ztufm8BCXHgaKMzCATNpVFRNVF8"
}

We use [JSON Web Tokens (JWT)](http://jwt.io/) to authorise access using bearer-tokens.
After providing your login credentials to the https://app.screenaware.com/api/auth/local endpoint (POST method), the request returns with a token property containing your bearer-token you can use in following requests

POST /auth/local

Parameter

Name Type Description
email

String

password

String

200

Name Type Description
token

String

bearer token to be used for subsequent API requests

401

Name Type Description
message

String

Error description

The API expects this bearer token to be included in all requests using the Authorization header like so:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...NJQiw9yy985VA

Example sending the bearer token as authorization with an API request:

# On the shell, you can just pass the correct header with each request
curl "https://app.screenaware.com/api/ENDPOINT"
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...NJQiw9yy985VA"

Integration

Get all Integrations for current user

Example JSON Response:

{
  "googleCalendar": {
    "key": "googleCalendar",
    "name": "Google Calendar",
    "description": "Include time spent in meetings or in transit to your activity data.",
    "status": "connected",
    "connected": true
  },
  "redmine": {
    "key": "redmine",
    "name": "Redmine",
    "description": "Relate spent activity time to tasks/projects you manage inside the Redmine app",
    "status": "not connected",
    "connected": false
  }
}

Returns the list of all third-party integrations for the user making the request.

GET /integrations

Required Role

user

Status Code: 200

Name Type Description
integrations Object

List of integrations

integrations.key String

Slugified name

integrations.name String

Name of the integration

integrations.description String

Brief verbal description

integrations.status String

Brief verbal status text for this integration

integrations.connected Bool

Indicates whether the user account is connected to the integration service with valid credentials currently.

Log

Submit Breakpad crash report

See https://chromium.googlesource.com/breakpad/breakpad/ for the expected BreakPad payload format

POST /logs/crash/sensor

Required Role

all

Parameter

Name Type Description
body string

Breakpad payload

Submit log point(s)

submit a single logpoint or an array of logpoints

POST /logs

Required Role

all

Parameter

Name Type Description
type String

alphanumeric identifier for this specific log point type. must only contain alphanumeric characters and underscores. example: info_sensor_snapshot_generate_duration

level String

one of: nothing, error, warn, info, debug, trace

data Object
data.time Time optional

Time when logpoint was taken in number of milliseconds since the Unix Epoch (as returned by Date#valueOf). If none is submitted, defaults to time when the point is processed by the ScreenAware server API

data.origin String

origin component responsible for generating the log point. e.g. “sensor-win” or “api”

data.originId String optional

unique identifier or name of the specific client instance sending the log point (e.g. persistent uuid generated in client app)

data.version SemVer

version of the origin component

data.userUuid String optional

uuid of the user triggering the action resulting in the logpoint. generally not available/necessary for low level debug/trace logpoints

data.message String

main flag for the logpoint type. preferably an enum such as “ok”, “fail”, “skipped” etc. which fragments all logpoints of this type into not more than ~5 groups

data.messageNumeric Double optional

if data.message can be parsed to an integer or double, thmessageNumeric will be automatically populated. setting this in the POST call will override any automatic parsing

data.messageBool Boolean optional

if data.message can be parsed to a bool value (“true”, “TRUE”), messageBool will be automatically populated. setting this in the POST call will override any automatic parsing

data.details String

detailed information which, unlike message, may well be totally specific for each individual log point. examples might be exception details, name of a URL which couldnt be categrized etc.

Get log entries of specified type

Example Request JSON Payload:

{
  "start": "2015-05-16T22:00:00.000Z",
  "structure": "grouped",
}

Example JSON Response:

[
    {
        "type": "client_auth",
        "level": "info",
        "uuid": "d1b039c5-6a96-4de8-8b21-fd3ecaf3afad",
        "time": "2015-12-02T17:21:30.051Z",
        "deleted": false,
        "details": "",
        "message": "success",
        "userUuid": "dd9fbc8a-7ef0-423e-8174-33a03e1ddd8b",
        "origin": "node",
        "version": "0.4.17"
    }
]

Returns all log points for log series matching the provided type

GET /logs/:type

Required Role

admin

Parameter

Name Type Description
type String

log type such as “sensor_scheduler_snapshotSend”

start IsoTime optional

Limit returned log points to entries created since start

Default value: 2daysAgo
end IsoTime optional

Limit returned log points to entries created before end

Default value: now
userUuid IsoTime optional

Only return log points relating to the user identified by the provided userUuid

structure String optional

When supplied and set to “grouped”, does not return the actual log entries, but the number of entries generated grouped in 5 minute intervals

metaonly String optional

When supplied and set to true, only returns metainformation about the result set. currently an object with “count” property is returned

Default value: false

Status Code: 200

Name Type Description
logPoint Object[]

Object containing the logged data poperties

logPoint.type String

identifier of the log point type.

logPoint.level String

Indicating urgency of the log popint [error

logPoint.uuid String

Unique identifier of the log entry

logPoint.time IsoTime

Timestamp when the log point was created (could be earlier than received by the ScreenAware server in cases where the log point was generated by the sensor or a third party service)

logPoint.deleted Boolean

Flag indicating whether the log point was marked to be deleted

logPoint.message String

Short dimensional indicator (typically along the lines of “ok”, “success”, “fail”)

logPoint.details String

Optional detailed information (e.g. exception details)

logPoint.userUuid String

Reference to the user this log point was generated for. Not all log points have a direct user reference though (e.g. database fallback logging)

logPoint.origin String

Reference to the component generating the log point. (node, client, sensorwin …)

logPoint.originId String

unique identifier or name of the specific client instance sending the log point (e.g. persistent uuid generated in client app)

logPoint.version SemVer

Version of the origin component

Get a single log entry by uuid

Example JSON Response:

{
    "type": "client_auth",
    "level": "info",
    "uuid": "d1b039c5-6a96-4de8-8b21-fd3ecaf3afad",
    "time": "2015-12-02T17:21:30.051Z",
    "deleted": false,
    "details": "",
    "message": "success",
    "userUuid": "dd9fbc8a-7ef0-423e-8174-33a03e1ddd8b",
    "origin": "node",
    "version": "0.4.17"
}

Returns a log entry object

GET /logs/point/:uuid

Required Role

admin

Parameter

Name Type Description
uuid String

Uuid of the log entry

time IsoTime

Optional timestamp of the logpoint (speeds up retrieval time)

Status Code: 200

Name Type Description
logPoint Object

Object containing the logged data poperties

logPoint.type String

identifier of the log point type.

logPoint.level String

Indicating urgency of the log popint [error

logPoint.uuid String

Unique identifier of the log entry

logPoint.time IsoTime

Timestamp when the log point was created (could be earlier than received by the ScreenAware server in cases where the log point was generated by the sensor or a third party service)

logPoint.deleted Boolean

Flag indicating whether the log point was marked to be deleted

logPoint.message String

Short dimensional indicator (typically along the lines of “ok”, “success”, “fail”)

logPoint.details String

Optional detailed information (e.g. exception details)

logPoint.userUuid String

Reference to the user this log point was generated for. Not all log points have a direct user reference though (e.g. database fallback logging)

logPoint.origin String

Reference to the component generating the log point. (node, client, sensorwin …)

logPoint.version SemVer

Version of the origin component

Get list of log series

Example JSON Response:

[
  {
      "type": "debug_activity_settings_settingsGetAll",
      "count": 177
  },
   {
      "type": "debug_relateDocument_urlBar_chrome",
      "count": 177
  }
]

Returns the list of distinct different log series (types) from the ScreenAware logging backend

GET /logs

Required Role

admin

Status Code: 200

Name Type Description
logs Object[]

List of log series identifiers

logs.type String

identifier of the log point series.

logs.count Number

number of times the log point type occured in the specified time range

Project

Create Project

Example Request JSON Payload:

{
    "uuid": "ac73ace6-cdf8-4180-b0c2-8b1751f839aa",
    "name": "ScreenAware",
    "parentProject": "f846f720-60a6-4ab4-b1ed-f5d5dae71c97",
    "localPaths": [],
    "contactEmails": [
        "otheremail@screenaware.com"
    ],
    "keywords": [
        "ScreenAware",
        "influxdb"
    ]
}

POST /projects

Required Role

user

Parameter

Name Type Description
project Object

Project object

project.uuid String

Project uuid

project.parentProject String

Uuid of another project this project is a child of. Projects can be nested in a 1-n (parent-child) relationship.

project.name String

Verbal name of the project

project.localPaths String[]

Local filesystem paths associated with the project (typically indicated by the user as containing project-related documents)

project.contactEmails String[]

Email addresses associated with the project (typically indicated by the user as contact persons for e.g. a client project)

project.keywords String[]

Verbal terms associated with the project (typically indicated by the user as describing the project or likely to occur in project related documents or communication)

Status Code: 201

Name Type Description
ok Boolean

Delete Project

DELETE /projects/:id

Required Role

user

Parameter

Name Type Description
id Number

Projects unique ID.

Status Code: 200

Name Type Description
project Object

Old project object in the state before deletion

Request Project Information

Example JSON Response:

{
    "id": "ac73ace6-cdf8-4180-b0c2-8b1751f839aa",
    "name": "ScreenAware",
    "userUuid": "d8abeaa0-466e-4228-8e93-404cb8cd984b",
    "parentProject": "f846f720-60a6-4ab4-b1ed-f5d5dae71c97",
    "localPaths": [
      "c:/myprojects/screenaware"
    ],
    "contactEmails": [
        "test@someemail.com"
    ],
    "keywords": [
        "ScreenAware",
        "otherKeyword"
    ]
}

Fetches the details of a specific project

GET /projects/:id

Required Role

user

Parameter

Name Type Description
id Number

Projects unique ID.

project Object

Project object

project.uuid String

Project uuid

project.name String

Verbal name of the project

project.userUuid String

Referencing the user the project object is attached to by user.uuid

project.parentProject String

Uuid of another project this project is a child of. Projects can be nested in a 1-n (parent-child) relationship.

project.localPaths String[]

Local filesystem paths associated with the project (typically indicated by the user as containing project-related documents)

project.contactEmails String[]

Email addresses associated with the project (typically indicated by the user as contact persons for e.g. a client project)

project.keywords String[]

Verbal terms associated with the project (typically indicated by the user as describing the project or likely to occur in project related documents or communication)

Request Projects

Fetches a list of all projects for the user making the request

GET /projects

Required Role

user

Status Code: 200

Name Type Description
projects Object[]

List of project objects

Update Project

Example Request JSON Payload:

{
    "uuid": "ac73ace6-cdf8-4180-b0c2-8b1751f839aa",
    "name": "ScreenAware",
    "parentProject": "f846f720-60a6-4ab4-b1ed-f5d5dae71c97",
    "localPaths": [],
    "contactEmails": [
        "otheremail@screenaware.com"
    ],
    "keywords": [
        "ScreenAware",
        "influxdb"
    ]
}

PUT /projects/:id

Required Role

user

Parameter

Name Type Description
project Object

Project object

project.uuid String

Project uuid

project.parentProject String

Uuid of another project this project is a child of. Projects can be nested in a 1-n (parent-child) relationship.

project.name String

Verbal name of the project

project.localPaths String[]

Local filesystem paths associated with the project (typically indicated by the user as containing project-related documents)

project.contactEmails String[]

Email addresses associated with the project (typically indicated by the user as contact persons for e.g. a client project)

project.keywords String[]

Verbal terms associated with the project (typically indicated by the user as describing the project or likely to occur in project related documents or communication)

Status Code: 200

Name Type Description
ok Boolean

Snapshot

Post a snapshot for current user

Example Request JSON Payload:

{
  "created": "2014-10-27T22:09:25.4864278+01:00",
  "durationMs": 8800,
  "windows": [
    {
      "documents": [],
      "processName": "devenv",
      "isFocused": true,
      "screenPercentage": 0.5052083333333334,
      "title": "ScreenAware (Running) - Microsoft Visual Studio",
      "visiblePercentage": 0.9897959183673469,
      "tags": {
        "firstTag": 5,
        "screenaware": 3,
        "thirdTag": 2
      }
    },
    {
      "documents": [
        {
          "path": "http://graphicriver.net/category/presentation-templates/powerpoint-templates",
          "title": "1100+ Powerpoint Templates - Powerpoint Themes | GraphicRiver - Google Chrome"
        }
      ],
      "processName": "chrome",
      "screenPercentage": 0.4895833333333333,
      "title": "1100+ Powerpoint Templates - Powerpoint Themes | GraphicRiver - Google Chrome",
      "visiblePercentage": 0.9791666666666666
    }
  ]
}

Submits the snapshot data for a specific timestamp, containing information regarding opened browser/application windows. Note that the endpoints accepts either a single snapshot object, or an array of snapshot objects sent in a batch manner.

POST /snapshots/

Required Role

user

Parameter

Name Type Description
snapshot Object

Snapshot object

snapshot.time String

Deprecated in favor of timeTaken parameter. Timestamp (ISO 8601) when the snapshot started. If left empty defaults to the time the snapshot is received by the API. Note that the time given here denotes the START of durationMs parameter

Default value: NOW-durationMs
snapshot.timeTaken String

Timestamp (ISO 8601) when the snapshot was taken. If left empty defaults to the time the snapshot is received by the API. Note that the time given here denotes the END of durationMs parameter

Default value: NOW-durationMs
snapshot.durationMs Integer

Timespan the snapshot covers in milliseconds. Max 10000 (10s).

Default value: 10000
snapshot.windows Object[] optional

Window objects detected when the snapshot was taken

snapshot.windows.title String optional

Title of the window (usually shown in a header bar of the window). Including application name typically appended at the end

snapshot.windows.isFocused String optional

Indicates whether the window has current user mouse/keboard focus (e.g. on MS Windows indicated by a highlighted window title bar)

Default value: false
snapshot.windows.processName String optional

Name of the system process the window belongs to. Typically specific to the application which the window belongs to

snapshot.windows.screenPercentage Number optional

Percentage of the screen the window covers (not considering overlapping of other windows)

snapshot.windows.visiblePercentage Number optional

Percentage of the window which is not covered by other windows or outsie of the monitor boundaries

snapshot.windows.tags Object optional

Tags generated by the sensor for this window object. Key being the tag, value a numeric double signifying th relative weight the tags have to each other. Note that any sort of anonymizing or removal of sensitive information has to be done on the sensor side

snapshot.windows.documents Object[] optional

Document objects opened in the window

snapshot.windows.documents.path string

URI of the document. Can be a local path or a web URL

snapshot.windows.documents.title string

Title of the document. This may, but does not have to, be equal to the window title

Status Code: 200

Name Type Description
ok Boolean

Stream

Get all streams for current user

Example Request JSON Payload:

{
  "start": "2015-05-16T22:00:00.000Z",
  "end": "2015-05-17T21:59:59.999Z",
  "minDuration": "180000",
  "showGaps": true
}

Example JSON Response:

[
  {
      "uuid": "e1b039c5-6a96-4de8-8b21-fd3ecaf3afad"
      "time": "2015-05-17T05:52:22.907Z",
      "durationMs": 287384,
      "projectUuid": "b3f60749-a2b8-4e45-a523-9614278e58a6",
  }
]

Returns the list of all streams within the given start/end parameters. A stream is a time span for which ScreenAware determined a common project context meaning a period without major task switches.

Optionally “gap streams” are inserted for periods which do not have streams allocated to them

GET /streams/

Required Role

user

Parameter

Name Type Description
start IsoTime

Only return streams which started at or after the specified time

Default value: startOfCurrentDay
end IsoTime

Only return streams which started at or before the specified time

Default value: endOfCurrentDay
minDuration Integer optional

Only return streams which have at least the specified durationMs in milliseconds

Default value: 0
projectUuid String optional

Project uuid to fetch streams for. If not specified gets all streams in the time period

limit Integer optional

Optional limit to use when requesting streams in a paginated way. Defaults to 1000. Max 10000

Default value: 1000
offset Integer optional

Optional offset to use when requesting streams in a paginated way

Default value: 0
sort String optional

Optional sort parameter. Currently only supports [‘time ASC’, 'time DESC’]

Default value: time ASC
expanded Boolean optional

Optional flag specifying whether applications, baseDocuments and titles from all substreams belonging to this stream should be included

Default value: false
showGaps Boolean optional

Optional flag specifying whether “gap streams” shall be inserted

Default value: false
groupByDay Boolean optional

Optional flag specifying whether the result should return streams in a nested hash grouped by day (keyed 'YYYY-MM-DD’)

Default value: false

Status Code: 200

Name Type Description
streams Array[]

Array of streams ordered by age (oldest to newest)

stream.uuid String

Stream uuid

stream.time IsoTime

Timestamp of the start of the stream

stream.durationMs Integer

Duration of the stream in milliseconds

stream.projectUuid String

Project uuid the stream was attributed to by ScreenAware. For gapStreams nothing is returned

stream.isGap Boolean

Only returned for gapStreams. For those value of true is set.

Update Project relation of a Stream

Example Request JSON Payload:

{
  "projectUuid": "b3f60749-a2b8-4e45-a523-9614278e58a6"
}

Allows manually or via a third party application to change/confirm the project relation of a Stream. This triggers a learning mechanism inside ScreenAware training the project-relation algorithmn for this user.

PUT /stream/:uuid/project

Required Role

user

Parameter

Name Type Description
projectUuid String

New project uuid as changed/confirmed by user

Status Code: 200

Name Type Description
ok Boolean

Substream

Get all substreams for current user

Example Request JSON Payload:

{
  "start": "2015-05-16T22:00:00.000Z",
  "end": "2015-05-17T21:59:59.999Z",
  "minDuration": "180000"
}

Example JSON Response:

[
  {
      "uuid": "e1b039c5-6a96-4de8-8b21-fd3ecaf3afad"
      "time": "2015-05-17T05:52:22.907Z",
      "durationMs": 287384,
      "projectUuid": "b3f60749-a2b8-4e45-a523-9614278e58a6",
      "categoryUuid": "c501477d-b5f1-4d62-8929-4b918bc998c7",
      "applicationUuid": "22673f8a-d728-4c08-b4a3-74f88d746fc5",
      "baseDocumentPath": "github.com",
      "projectRelationReason": "file part '/myProjectFolder' was found in document path"
  }
]

Returns the list of all substreams within the given start/end parameters. A substream is a time span for which ScreenAware detected a common application (by processName) and baseDocument (as in domain or filename)

GET /substreams/

Required Role

user

Parameter

Name Type Description
start IsoTime

Only return substreams which started at or after the specified time

Default value: startOfCurrentDay
end IsoTime

Only return substreams which started at or before the specified time

Default value: endOfCurrentDay
minDuration Integer optional

Only return substreams which have at least the specified durationMs in milliseconds

Default value: 0
limit Integer optional

Optional limit to use when requesting streams in a paginated way. Defaults to 1000. Max 10000

Default value: 1000
offset Integer optional

Optional offset to use when requesting streams in a paginated way

Default value: 0
sort String optional

Optional sort parameter. Currently only supports ['time ASC’, 'time DESC’]

Default value: time ASC

Status Code: 200

Name Type Description
substreams Array[]

Array of streams ordered by age (oldest to newest)

substream.uuid String

Stream uuid

substream.time IsoTime

Timestamp of the start of the stream

substream.durationMs Integer

Duration of the stream in milliseconds

substream.projectUuid String

Project uuid the stream was attributed to by ScreenAware. For gapStreams nothing is returned

substream.categoryUuid String

Category uuid the stream was attributed to by ScreenAware. For gapStreams nothing is returned

substream.applicationUuid String

Application uuid the stream was attributed to by ScreenAware. For gapStreams nothing is returned

substream.baseDocumentPath String

BaseDocumentPath for websites this consists of the top-level, second-level and third-level domain parts. So no url fragments or query parameters. for local files it is the filename+extension without directory paths

substream.projectRelationReason String

Verbal description why the substream was attributed to this project

Task

Request Task Information

Example JSON Response:

{
    "uuid": "ac73ace6-cdf8-4180-b0c2-8b1751f839aa",
    "title": "Smile at a stranger every day",
    "projectUuid": "f846f720-60a6-4ab4-b1ed-f5d5dae71c97",
    "userUuid": "846f7204-60a6-4ab4-b1ed-f5d5dae7188d"
}

Fetches the details of a specific task

GET /tasks/:id

Required Role

user

Parameter

Name Type Description
id String

Task unique ID.

task Object

Task object

task.uuid String

Task unique identifier

task.title String

Task title

task.projectUuid String

Project uuid this task belongs to

task.userUuid String

Uuid of user this task belongs to (typically yourself)

Request Tasks

Fetches a list of all tasks for the user making the request

GET /tasks

Required Role

user

Status Code: 200

Name Type Description
tasks Object[]

List of task objects

Time

Get logged time for current user

Example Request JSON Payload:

{
  "start": "2015-05-16T22:00:00.000Z",
  "end": "2015-05-17T21:59:59.999Z",
  "groupBy": "projectUuid",
  "resolution": "day"
  "nestTimeBucketsInsideGroups": false
}

Example JSON Response with a single result (no groupBy or resolution parameters specified)

{
    "start": "2010-10-14T22:00:00.000Z",
    "end": "2010-10-15T21:59:59.999Z",
    "sum": 270000
}

Example JSON Response when using groupBy='projectUuid’ parameter (categoryUuid and applicationUuid would be analogous):

{
    "start": "2012-05-23T22:00:00.000Z",
    "end": "2012-05-24T21:59:59.999Z",
    "sum": 270000,
    "groupType": "projectUuid",
    "grouped": {
        "0fcdd1ec-05f7-49cc-931f-530c2c2f085c": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-24T21:59:59.999Z",
            "sum": 90000,
            "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c"
        },
        "98254cc5-b623-43b6-8537-d9e0122cf975": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-24T21:59:59.999Z",
            "sum": 90000,
            "projectUuid": "98254cc5-b623-43b6-8537-d9e0122cf975"
        },
        "fe79e96c-a8ff-4ead-90eb-2c799db17439": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-24T21:59:59.999Z",
            "sum": 90000,
            "projectUuid": "fe79e96c-a8ff-4ead-90eb-2c799db17439"
        }
    }
}

Example JSON Response nested by time bucket (resolution='hour’):

{
    "start": "2012-05-23T22:00:00.000Z",
    "end": "2012-05-24T21:59:59.999Z",
    "sum": 270000,
    "groupType": "time",
    "grouped": {
        "2012-05-23T22:00:00.000Z": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-23T23:00:00.000Z",
            "sum": 270000
        },
        "2012-05-23T23:00:00.000Z": {
            "start": "2012-05-23T23:00:00.000Z",
            "end": "2012-05-24T00:00:00.000Z",
            "sum": 0
        }
    }
}

Example JSON Response nested by time bucket and projectUuid (groupBy='projectUuid’ and resolution='hour’):

{
    "start": "2012-05-23T22:00:00.000Z",
    "end": "2012-05-24T21:59:59.999Z",
    "sum": 270000,
    "groupType": "time",
    "grouped": {
        "2012-05-23T22:00:00.000Z": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-23T23:00:00.000Z",
            "sum": 18000,
            "groupType": "projectUuid",
            "grouped": {
                "0fcdd1ec-05f7-49cc-931f-530c2c2f085c": {
                    "start": "2012-05-23T22:00:00.000Z",
                    "end": "2012-05-23T23:00:00.000Z",
                    "sum": 9000,
                    "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c"
                },
                "98254cc5-b623-43b6-8537-d9e0122cf975": {
                    "start": "2012-05-23T22:00:00.000Z",
                    "end": "2012-05-23T23:00:00.000Z",
                    "sum": 0,
                    "projectUuid": "98254cc5-b623-43b6-8537-d9e0122cf975"
                },
                "fe79e96c-a8ff-4ead-90eb-2c799db17439": {
                    "start": "2012-05-23T22:00:00.000Z",
                    "end": "2012-05-23T23:00:00.000Z",
                    "sum": 0,
                    "projectUuid": "fe79e96c-a8ff-4ead-90eb-2c799db17439"
                }
            }
        },
        "2012-05-23T23:00:00.000Z": {
            "start": "2012-05-23T23:00:00.000Z",
            "end": "2012-05-24T00:00:00.000Z",
            "sum": 9000,
            "groupType": "projectUuid",
            "grouped": {
                "0fcdd1ec-05f7-49cc-931f-530c2c2f085c": {
                    "start": "2012-05-23T23:00:00.000Z",
                    "end": "2012-05-24T00:00:00.000Z",
                    "sum": 0,
                    "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c"
                },
                "98254cc5-b623-43b6-8537-d9e0122cf975": {
                    "start": "2012-05-23T23:00:00.000Z",
                    "end": "2012-05-24T00:00:00.000Z",
                    "sum": 0,
                    "projectUuid": "98254cc5-b623-43b6-8537-d9e0122cf975"
                },
                "fe79e96c-a8ff-4ead-90eb-2c799db17439": {
                    "start": "2012-05-23T23:00:00.000Z",
                    "end": "2012-05-24T00:00:00.000Z",
                    "sum": 9000,
                    "projectUuid": "fe79e96c-a8ff-4ead-90eb-2c799db17439"
                }
            }
        }
    }
}

Example JSON Response nested by projectUuid and time bucket (groupBy='projectUuid’ and resolution='hour’ and nestTimeBucketsInsideGroups=true):

{
    "start": "2012-05-23T22:00:00.000Z",
    "end": "2012-05-24T21:59:59.999Z",
    "sum": 270000,
    "groupType": "projectUuid",
    "grouped": {
        "0fcdd1ec-05f7-49cc-931f-530c2c2f085c": {
            "start": "2012-05-23T22:00:00.000Z",
            "end": "2012-05-24T21:59:59.999Z",
            "sum": 90000,
            "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c",
            "groupType": "time",
            "grouped": {
                "2012-05-23T22:00:00.000Z": {
                    "start": "2012-05-23T22:00:00.000Z",
                    "end": "2012-05-23T23:00:00.000Z",
                    "sum": 9000,
                    "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c"
                },
                "2012-05-23T23:00:00.000Z": {
                    "start": "2012-05-23T23:00:00.000Z",
                    "end": "2012-05-24T00:00:00.000Z",
                    "sum": 18000,
                    "projectUuid": "0fcdd1ec-05f7-49cc-931f-530c2c2f085c"
                }
            }
        }
    }
}

Returns the screen time a user has logged, optionally grouped by projectUuid and/or time buckets (hours, days)

GET /times/

Required Role

user

Parameter

Name Type Description
start IsoTime

Only return times which started at or after the specified time

Default value: startOfCurrentDay
end IsoTime

Only return times which started at or before the specified time

Default value: endOfCurrentDay
groupBy String optional

Optional string to specify grouping by related entity. Possible: ['projectUuid’, 'categoryUuid’, 'applicationUuid’]

resolution String optional

Optional string specifying time buckets to group the results into. Possible: ['hour’, 'day’, 'week’, 'month’]

nestTimeBucketsInsideGroups Boolean optional

Optional flag indicating whether time-entries should be grouped timeBucket->groupByKey->time (default) or groupByKey->timeBucket->time. Only has any effect if both groupBy as well as resolution parameters have been passed.

Default value: false

Status Code: 200

Name Type Description
time Object

object with duration (sum) and start/end Time entries. Potentially nested twice - see examples

User

Create User

Example Request JSON Payload:

{
  "email": "ilikecows@gmail.com",
  "password": "supersecretohyeah",
  "nameFirst": "Peter",
  "nameLast": "Shaw"
}

POST /users

Required Role

admin

Parameter

Name Type Description
user Object

User object

user.email String

User email address

user.nameFirst String optional

First name of the user

user.nameLast String optional

Last name of the user

user.password String

Password

Status Code: 201

Name Type Description
json Object

object containing {token: 'tokencode123…’} token JWT bearer token

Delete User

DELETE /users/:id

Required Role

admin

Parameter

Name Type Description
id Number

Users unique ID.

Status Code: 200

Name Type Description
user Object

User object

Get Own User

Example JSON Response:

 {
   "_id": "5550d18439a4e01037d1c7c4",
   "email": "someuser@somedomain.com",
   "integrations": {
     "googleCalendar": {
       "calendars": []
     },
     "redmine": {
       "projects": []
     }
   },
   "nameFirst": "John",
   "nameLast": "Dove",
   "role": {
     "bitMask": 2,
     "title": "user"
  }
}

Fetches your own user object associated with your JWT bearer token

GET /users/me

Required Role

user

Status Code: 200

Name Type Description
user Object

User object

user._id String

User id

user.email String

User email address

Request User information

Example JSON Response:

 {
   "_id": "5550d18439a4e01037d1c7c4",
   "email": "someuser@somedomain.com",
   "integrations": {
     "googleCalendar": {
       "calendars": []
     },
     "redmine": {
       "projects": []
     }
   },
   "nameFirst": "John",
   "nameLast": "Dove",
   "role": {
     "bitMask": 2,
     "title": "user"
  }
}

GET /users/:id

Required Role

admin

Parameter

Name Type Description
id Number

Users unique ID.

Status Code: 200

Name Type Description
user Object

User object

user._id String

User id

user.email String

User email address

Request Users

Fetches a list of all user objects

GET /users

Required Role

admin

Status Code: 200

Name Type Description
users Object[]

List of user objects

Update User

Example Request JSON Payload:

{
  "email": "ilikecows@gmail.com",
  "password": "supersecretohyeah",
  "nameFirst": "Peter",
  "nameLast": "Shaw"
}

PUT /users

Required Role

admin

Parameter

Name Type Description
user Object

User object

user.email String

User email address

user.nameFirst String optional

First name of the user

user.nameLast String optional

Last name of the user

user.password String

Password

Status Code: 200

Name Type Description
ok Boolean

Update User Password

PUT /users/:id/password

Required Role

admin

Parameter

Name Type Description
id Number

Users unique ID

password String

New user password

Status Code: 200

Name Type Description
ok Boolean

Errors

The ScreenAware API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with ScreenAware’s servers.

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The resource requested is not available for your role (probably administrators only)
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method (not implemented yet)
406 Not Acceptable – You requested a format that isn’t json (not implemented yet)
410 Gone – The requested resource has been removed from our servers (not implemented yet)
429 Too Many Requests – You’re sending too many requests too fast! Slow down! (not implemented yet)
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Changelog