{
  "openapi": "3.1.0",
  "info": {
    "title": "enfoKT local API",
    "version": "1",
    "summary": "Read the timer and manage your tasks in enfoKT from scripts and AI agents on the same computer.",
    "description": "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.",
    "contact": {
      "name": "enfoKT",
      "url": "https://enfokt.soyitiel.com/"
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:47525",
      "description": "enfoKT on this computer"
    }
  ],
  "security": [],
  "paths": {
    "/v1/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "The timer right now",
        "description": "No key needed.",
        "responses": {
          "200": {
            "description": "The timer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/tasks": {
      "get": {
        "operationId": "listTasks",
        "summary": "List tasks",
        "description": "Pending tasks first, in their order, then done tasks, most recent first (at most 500 are kept).",
        "security": [
          {
            "key": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only pending or only done tasks.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "done"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The tasks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "operationId": "createTasks",
        "summary": "Add one task or several",
        "description": "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.",
        "security": [
          {
            "key": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/NewTask"
                  },
                  {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "$ref": "#/components/schemas/NewTask"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The tasks just added.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "delete": {
        "operationId": "deleteTasks",
        "summary": "Delete several tasks",
        "description": "Pending or done. If any id does not exist, nothing is deleted. Without `ids` it answers 400: it never deletes everything by accident.",
        "security": [
          {
            "key": []
          }
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Task ids, separated by commas.",
            "schema": {
              "type": "string"
            },
            "example": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77,019a9f3c-6a10-7f02-9c11-0b5e8d3a2c19"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/tasks/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The task id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getTask",
        "summary": "One task",
        "security": [
          {
            "key": []
          }
        ],
        "responses": {
          "200": {
            "description": "The task.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "operationId": "updateTask",
        "summary": "Change a task",
        "description": "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.",
        "security": [
          {
            "key": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskChange"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "deleteTask",
        "summary": "Delete a task",
        "security": [
          {
            "key": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "key": {
        "type": "http",
        "scheme": "bearer",
        "description": "The key in `api-key.txt`, in enfoKT's data folder. It exists only while \"Permitir control por API\" is on; \"Cambiar llave\" replaces it."
      }
    },
    "schemas": {
      "Status": {
        "type": "object",
        "required": [
          "phase",
          "state",
          "remaining_seconds",
          "total_seconds",
          "round",
          "rounds",
          "focus_today",
          "current_task",
          "ambient_playing"
        ],
        "properties": {
          "phase": {
            "type": "string",
            "enum": [
              "focus",
              "break"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "waiting",
              "running",
              "paused"
            ]
          },
          "remaining_seconds": {
            "type": "integer",
            "minimum": 0
          },
          "total_seconds": {
            "type": "integer",
            "minimum": 0
          },
          "round": {
            "type": "integer",
            "description": "The round of the cycle, from 1."
          },
          "rounds": {
            "type": "integer",
            "description": "Rounds in the cycle."
          },
          "focus_today": {
            "type": "integer",
            "description": "Focus sessions finished today."
          },
          "current_task": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "ambient_playing": {
            "type": "boolean",
            "description": "Whether an ambient sound is playing."
          }
        },
        "example": {
          "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
        }
      },
      "Task": {
        "type": "object",
        "required": [
          "id",
          "name",
          "notes",
          "status",
          "position",
          "current",
          "done_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID version 7."
          },
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "notes": {
            "type": "string",
            "maxLength": 10000
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "done"
            ]
          },
          "position": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Place in the queue, from 0. Null for done tasks."
          },
          "current": {
            "type": "boolean",
            "description": "The task enfoKT is reminding you of now."
          },
          "done_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "example": {
          "id": "019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77",
          "name": "Write the report",
          "notes": "",
          "status": "pending",
          "position": 0,
          "current": true,
          "done_at": null
        }
      },
      "TaskList": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Task"
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "current_id"
            ],
            "properties": {
              "current_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      },
      "NewTask": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Cannot be empty; cut at 80 characters."
          },
          "notes": {
            "type": "string",
            "description": "Free text, up to 10,000 characters."
          }
        },
        "example": {
          "name": "Write the report",
          "notes": "Use last month's numbers."
        }
      },
      "TaskChange": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "New name. Cannot be empty; cut at 80 characters."
          },
          "notes": {
            "type": "string",
            "description": "New notes. Replaces the old ones; an empty string clears them."
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "description": "Pending tasks only."
          },
          "current": {
            "const": true,
            "description": "Makes it the current task. Pending tasks only."
          },
          "done": {
            "type": "boolean",
            "description": "true marks it done; false brings it back to the queue."
          }
        },
        "example": {
          "name": "Write the report (final)",
          "position": 0
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457, served as application/problem+json.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          }
        },
        "example": {
          "type": "about:blank",
          "title": "Not Found",
          "status": 404,
          "detail": "No task with id 019a9f3c-5b2e-7c41-8d6a-2f1e9b0c4a77."
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Something in the request does not fit. Nothing changed.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or wrong key.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API is off, the request comes from a web page, or the Host is not this computer.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such task or route.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    }
  }
}
