Skip to content

Latest commit

 

History

History
96 lines (59 loc) · 2.55 KB

rest.rst

File metadata and controls

96 lines (59 loc) · 2.55 KB

REST API

ActivityWatch uses a REST API for all communication between aw-server and clients. Most applications should never use HTTP directly but should instead use the client libraries available. If no such library yet exists for a given language, this document is meant to provide enough specification to create one.

Warning

The API is currently under development, and is subject to change. It will be documented in better detail when first version has been frozen.

Note

Part of the documentation might be outdated, you can get up-to-date API documentation in the API browser available from the web UI of your aw-server instance.

REST Security

Note

Our current security consists only of not allowing non-localhost connections, this is likely to be the case for quite a while.

Clients might in the future be able to have read-only or append-only access to buckets, providing additional security and preventing compromised clients from being able to cause a severe security breach. All clients will probably also encrypt data in transit.

REST Reference

Note

This reference is highly incomplete. For an interactive view of the API, try out the API playground running on your local server at: http://localhost:5600/api/

Buckets API

The most common API used by ActivityWatch clients is the API providing read and append access buckets. Buckets are data containers used to group data together which shares some metadata (such as client type, hostname or location).

Get

GET /api/0/buckets/<bucket_id>

List

GET /api/0/buckets/

Create

POST /api/0/buckets/<bucket_id>

Events API

The most common API used by ActivityWatch clients is the API providing read and append Events <event-model> to buckets. Buckets are data containers used to group data together which shares some metadata (such as client type, hostname or location).

Get events

GET /api/0/buckets/<bucket_id>/events

Create event

POST /api/0/buckets/<bucket_id>/events

Heartbeat API

The heartbeat API is one of the most useful endpoints for writing watchers.

POST /api/0/buckets/<bucket_id>/heartbeat

View API

Warning

This API should not be relied on. It's messy and has a bunch of issues that we hope to resolve by designing it.

No documentation here, because you shouldn't use it (yet).