enfoKT local API

Read the timer and manage your tasks in enfoKT from scripts and AI agents on the same computer.

enfoKT is a focus timer with ambient sounds for Windows. While it runs, it listens on 127.0.0.1:47525, only on your own computer. Nothing reaches the internet. Reading the timer is open. Tasks need the API turned on in enfoKT (Ajustes, Avanzado, "Permitir control por API") and the key from the file api-key.txt in enfoKT's data folder (Ajustes, Avanzado, "Copiar ruta de la llave" copies its path), sent as Authorization: Bearer <key>. Requests from web pages (with an Origin header) and with a Host other than 127.0.0.1 or localhost are rejected.

Start

  1. In enfoKT, open Ajustes, then Avanzado, and turn on Permitir control por API.
  2. Press Copiar ruta de la llave. That copies the path of the file with your key, usually %APPDATA%\com.soyitiel.enfokt\api-key.txt.
  3. Ask for the timer (no key needed):
    curl http://127.0.0.1:47525/v1/status
  4. Read the key and list your tasks. In PowerShell:
    $KEY = Get-Content "$env:APPDATA\com.soyitiel.enfokt\api-key.txt"
    curl.exe http://127.0.0.1:47525/v1/tasks -H "Authorization: Bearer $KEY"

The key changes only when you press Cambiar llave, and disappears when you turn the API off. If it ever leaks, change it.

From an AI agent

Agents such as Claude Code or Codex can use it from your computer. Turn the API on, then paste something like this:

enfoKT is running on this computer. Its local API is described at
https://enfokt.soyitiel.com/api/openapi.json. The key is in the file at <paste the path from "Copiar ruta de la llave">;
send it as "Authorization: Bearer <key>". Add these tasks for me, in this order: ...

Endpoints

GET /v1/status no key

The timer right now.

No key needed.

200

The timer.

{
  "phase": "focus",
  "state": "running",
  "remaining_seconds": 1499,
  "total_seconds": 1500,
  "round": 2,
  "rounds": 4,
  "focus_today": 6,
  "current_task": {
    "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
    "name": "Write the report"
  },
  "ambient_playing": false
}

Errors: 403 The API is off, the request comes from a web page, or the Host is not this computer.

GET /v1/tasks needs the key

List tasks.

Pending tasks first, in their order, then done tasks, most recent first (at most 500 are kept).

ParameterInWhat
status optionalqueryOnly pending or only done tasks. (pending or done)

200

The tasks.

{
  "data": [
    {
      "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
      "name": "Write the report",
      "notes": "",
      "status": "pending",
      "position": 0,
      "current": true,
      "done_at": null
    }
  ],
  "meta": {}
}

Errors: 400 Something in the request does not fit. Nothing changed. 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer.

POST /v1/tasks needs the key

Add one task or several.

Added at the end of the queue, in the order given. If any task has no name, nothing is added. Names longer than 80 characters are cut; notes, at 10,000. To split work into steps, add each step as its own task, in order, and put the shared context in their notes.

Body

FieldWhat
nameCannot be empty; cut at 80 characters.
notes optionalFree text, up to 10,000 characters.

Or a list of them, to add several at once.

{
  "name": "Write the report",
  "notes": "Use last month's numbers."
}

201

The tasks just added.

{
  "data": [
    {
      "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
      "name": "Write the report",
      "notes": "",
      "status": "pending",
      "position": 0,
      "current": true,
      "done_at": null
    }
  ]
}

Errors: 400 Something in the request does not fit. Nothing changed. 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer.

DELETE /v1/tasks needs the key

Delete several tasks.

Pending or done. If any id does not exist, nothing is deleted. Without ids it answers 400: it never deletes everything by accident.

ParameterInWhat
idsqueryTask ids, separated by commas.

204

Deleted.

Errors: 400 Something in the request does not fit. Nothing changed. 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer. 404 No such task or route.

GET /v1/tasks/{id} needs the key

One task.

ParameterInWhat
idpathThe task id (a UUID).

200

The task.

{
  "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
  "name": "Write the report",
  "notes": "",
  "status": "pending",
  "position": 0,
  "current": true,
  "done_at": null
}

Errors: 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer. 404 No such task or route.

PATCH /v1/tasks/{id} needs the key

Change a task.

Send only what changes. Applied in this order: done: false (back to the queue), name and notes, position, current, and done: true last. So {"done": false, "position": 0} brings a done task back to the top. Marking it done plays the same sound as in the app. If anything in the request does not fit, nothing changes.

ParameterInWhat
idpathThe task id (a UUID).

Body

FieldWhat
name optionalNew name. Cannot be empty; cut at 80 characters.
notes optionalNew notes. Replaces the old ones; an empty string clears them.
position optionalPending tasks only.
current optionalMakes it the current task. Pending tasks only.
done optionaltrue marks it done; false brings it back to the queue.
{
  "name": "Write the report (final)",
  "position": 0
}

200

The task after the change.

{
  "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
  "name": "Write the report",
  "notes": "",
  "status": "pending",
  "position": 0,
  "current": true,
  "done_at": null
}

Errors: 400 Something in the request does not fit. Nothing changed. 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer. 404 No such task or route.

DELETE /v1/tasks/{id} needs the key

Delete a task.

ParameterInWhat
idpathThe task id (a UUID).

204

Deleted.

Errors: 401 Missing or wrong key. 403 The API is off, the request comes from a web page, or the Host is not this computer. 404 No such task or route.

Errors

Errors follow RFC 9457 (application/problem+json). detail says what went wrong, in plain English:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No task with id 019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77."
}

Changes are all or nothing: if anything in a request does not fit, nothing changes. A 405 comes with an Allow header listing the methods the route takes.

Good to know

Task ids are UUIDs (version 7). Times are ISO 8601 in UTC. The API version is in the path (/v1): a change that breaks something gets a new version.

This page is generated from openapi.json, the source of truth.