Documentation

Getting Started

Pomocutie is a pomodoro timer with a built-in to-do list. Here's the rhythm:

• Pick a task from your list and hit Start to run a focus session.
• Work until the timer rings, then take a short break.
• Every session you complete counts toward that task's pomodoro estimate.
• After a few pomodoros, the timer suggests a longer break.

You can use Pomocutie as a guest (your data stays in your browser) or create a free account to keep everything synced on the server.

Notes & Tasks

The Notes page has three tabs:

• Notes — free-form notes, rich text supported. You can convert a note into a task anytime.
• Tasks — actionable items with a pomodoro estimate. Tap the circle to mark one done.
• Completed — everything you've finished.

The editor is a rich text (WYSIWYG) editor, so you can bold, italicize, add headers and lists just like a word processor. It's stored as Markdown under the hood.

Tasks synced from the LMS appear at the top of the Tasks tab, grouped by course, with their due date and a link straight to the assignment.

Reports

Visit Reports to see a monthly calendar of your focus sessions, your current streak, and how many minutes you've spent in deep work each day.

Task Sync API

Pomocutie exposes a small HTTP API so a scraper (or any external tool) can push school assignments into the app. The scraper runs daily, so the API is designed to be idempotent — re-sending the same assignments won't create duplicates.

Sync tasks

POST /api/tasks/sync

Accept a batch of assignments. Tasks are matched by their source_id:

• New source_id → task is created.
• Known source_id with changes → task is updated.
• Known source_id unchanged → task is skipped.

Request body:

{
  "tasks": [
    {
      "source_id": "lms-{assignment_id}",
      "title": "Assignment 1: Research Paper",
      "course": "COE 101",
      "due_date": "2026-08-15T23:59:00",
      "description": "Submit via LMS portal",
      "url": "https://lcc-welearn.neolms.com/..."
    }
  ]
}

Fields:

• source_id required — unique identifier from the source system. Used for deduplication.
• title required — assignment name.
• course required — course code or subject label. Used to group tasks in the UI.
• due_date — ISO 8601 timestamp. Optional.
• description — extra details shown in the task card. Optional.
• url — link to the assignment in the LMS. Optional.

Example request

curl -X POST https://pomocutie.space/api/tasks/sync \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {
        "source_id": "lms-12345",
        "title": "Assignment 1: Research Paper",
        "course": "COE 101",
        "due_date": "2026-08-15T23:59:00",
        "description": "Submit via LMS portal",
        "url": "https://lcc-welearn.neolms.com/..."
      }
    ]
  }'

Response:

{
  "message": "Sync completed.",
  "upserted": 1,
  "skipped": 0
}

• upserted — tasks that were created or updated.
• skipped — tasks already in sync, left untouched.

The endpoint returns 401 Unauthorized if the API key is missing or wrong, and 422 Unprocessable Content if the payload is invalid.

Personal API keys

Signed-in users can generate their own API keys to let scripts read and write their notes and tasks. Unlike the shared scraper key, personal keys are tied to your account and can be revoked anytime.

Generate a key from Settings → API. The key is shown exactly once when created — copy it somewhere safe. Keys are stored hashed on the server, so they can't be recovered later. You can name keys (e.g. "my script") and revoke them from the same screen.

Notes & Tasks CRUD

Both /api/notes and /api/tasks support the same operations:

• GET /api/tasks — list all tasks.
• POST /api/tasks — create a task.
• GET /api/tasks/{id} — fetch one task.
• PATCH /api/tasks/{id} — update a task (only the fields you send).
• DELETE /api/tasks/{id} — delete a task.

Create a task:

curl -X POST https://pomocutie.space/api/tasks \
  -H "Authorization: Bearer pomocutie_your-personal-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Finish lab report",
    "content_markdown": "Write the discussion section.",
    "target_pomodoros": 3
  }'

Common fields:

• title — short name. Optional if content is provided.
• content / content_markdown — Markdown body.
• content_html — HTML body (optional, sanitized on save).
• target_pomodoros / completed_pomodoros — task estimates (tasks only).
• is_completed — mark done (boolean).

A successful create returns 201, and reads return the item as JSON inside a data object. The same shape is used for both notes and tasks.