Guides / The local API

The local API

Another app on your computer can start and stop HourSlip's timer and ask what is running. A browser that groups tabs by client, a launcher, a script of your own: anything that can make an HTTP request. It is off until you turn it on, and nothing leaves your computer.

Turn it on

Open Settings › General and find Local API.
Switch on Let other apps control the timer (Allow other apps on Windows and Linux).
Copy the Address and the Token into the other app.

The address is http://127.0.0.1:47821 unless you change the port. The token is a long random password that HourSlip makes the first time you switch the API on. Every request has to carry it.

HourSlip listens whenever it is running, including when only the menu bar or tray icon is showing. If the line under the address says the port is in use by another program, type a different port (1024 to 65535) and give the other app the new address.

Anyone with the token can start and stop your timer. If it ends up somewhere it shouldn't, press Regenerate…: the old token stops working at once, and each app needs the new one.

Try it

With a client called Acme and a project called Website, in a terminal:

curl http://127.0.0.1:47821/v1/timer/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"client": "Acme", "project": "Website", "notes": "Homepage"}'

The timer starts in HourSlip and the reply says what is running:

{"running": true, "client": "Acme", "project": "Website", "notes": "Homepage", "start": "2026-10-07T09:00:00Z"}

The three requests

Every request needs the header Authorization: Bearer YOUR_TOKEN. Bodies and replies are JSON.

Request	What it does
`GET /v1/timer`	Reports the timer.
`POST /v1/timer/start`	Stops whatever is running and starts the project you name.
`POST /v1/timer/stop`	Stops the timer. Succeeds when nothing is running too.

Starting

The body names the client and the project, and may carry notes for the entry. Names are matched the way the CSV import matches them: capitals and spaces around the name don't matter. The client is needed because two clients can each have a project called Website.

Starting does what the menu bar does. The running entry ends at that moment and a new one begins, even when it is the same project again.

The reply

All three answer with the timer as it is afterwards: {"running": false}, or running, client, project, notes and start. Client and project come back spelled as they are in HourSlip. start is in UTC.

To keep another app's display up to date, ask GET /v1/timer every few seconds. If the connection is refused, HourSlip isn't running or the API is off.

Errors

An error is an HTTP status and a body with a code for programs and a sentence for people: {"error": "unknown_project", "message": "…"}.

Status and code	When
400 `bad_request`	The body isn't JSON, or client or project is missing or empty.
401 `unauthorized`	The token is missing or wrong.
403 `forbidden_origin`	The request came from a web page, or was addressed to a name other than 127.0.0.1 or localhost.
404 `unknown_project`	HourSlip has no such client and project, or the project is archived.
404 `not_found`	Any other path.
405 `method_not_allowed`	The right path with the wrong method.
409 `needs_answer`	HourSlip is waiting for you to keep or discard away time. See below.
413 `too_large`	The request is over 64 KB.
503 `unavailable`	HourSlip can't answer right now, for example while it is starting or quitting.

The API never creates anything. A client or project that doesn't exist is an error, so a typing mistake in another app can't add clients to your books. Add it in HourSlip first.

Away time

When the computer sleeps or sits idle with the timer running, HourSlip asks whether to keep or discard that time before the entry ends. An app can't answer that for you. Until you do, start and stop are refused with 409 needs_answer and change nothing; GET /v1/timer still works. Answer the question in HourSlip and the next request goes through.

Who can reach it

Only this computer. HourSlip listens on 127.0.0.1, which other devices on your network can't connect to.
Only apps with the token. On a Mac it is kept in your keychain; on Windows and Linux in a file only your account can read. It isn't part of backups or exports.
Not web pages. A request sent by a page in a browser is refused even with the right token, so no site you visit can touch the timer. A browser extension that wants to use the API needs a helper app of its own.
Only the running timer. The API shows the current client, project, notes and start time. It can't list your clients, read past entries or see rates and invoices.

What it doesn't do

This first version starts, stops and reports. It doesn't list or create clients and projects, add finished entries (the CSV import does that), or notify other apps when the timer changes. It works the same on Mac, Windows and Linux and in the free version. If you're building something on it and need more, tell us.