Help

TimeboardApp is a lightweight task tracker with tags, recurring tasks, notifications, and a complete JSON API.

Core concepts

Tasks

Tags

Tags are global (per installation) but tasks are always scoped to a user account. Tags are used for filtering and for routing notifications.

Past-due tag bar

Each user can enable Profile → Dashboard shortcuts → Show frozen past-due tag bar. When enabled, a sticky top bar lists tags assigned to active past-due tasks and opens a dashboard tab filtered to the selected tag.

ChatGPT

TimeboardApp 00.14.00 includes an experimental native MCP connection for ChatGPT. Each person signs in with their own TimeboardApp account and approves the requested permissions. MCP is disabled by default; an administrator must enable it on a publicly reachable HTTPS installation.

Native MCP is enabled on this installation. You can review approved applications under Profile → Connected applications.

Connect your account

  1. Ask your administrator for this installation's public MCP address, such as https://tasks.example.com/mcp.
  2. In ChatGPT, open Plugins → + → Add custom MCP server. Enter that address, choose OAuth, and create the plugin. Availability depends on your ChatGPT account and workspace settings.
  3. Sign in on the TimeboardApp page. Check the account name and requested permissions, then select Allow access, or Cancel to decline.
  4. Start a new ChatGPT conversation and select the plugin with @. Ask it to identify your account and list your tasks before creating a disposable test task.

You do not need an OpenAI API key or a copied TimeboardApp API token. If ChatGPT displays a callback address that the server rejects, give the exact address to your administrator so they can configure it and restart the service. Administrator setup and troubleshooting are in the ChatGPT integration guide.

Permissions and task changes

The connection offers eleven tools, subject to the permissions shown on the consent page:

Native MCP permissions
PermissionWhat it allows
tasks:readIdentify your account, list or search your tasks, read a task, and summarize your task counts.
tasks:writeCreate, update, complete, archive, and restore your tasks.
users:readList eligible assignees by username and ID.
tasks:assignTransfer an active standalone task you own to an eligible assignee.

Disconnect an application

Open Profile → Connected applications → Manage connections, review the application's permissions, and select Disconnect. This immediately stops its access to your account. Reconnect and approve access again if you want to use it later. Changing your TimeboardApp password also invalidates existing MCP connections.

Existing private GPT Actions

Private GPT Actions remain available separately, with eight task operations at /api/chatgpt. They use a scoped integration token and the /openapi-chatgpt.json schema instead of MCP OAuth. Existing Actions configurations keep working when MCP is disabled. Their tokens are managed separately; disconnecting an MCP application does not revoke an Actions token.

Notifications

Notifications are configured per user via Profile → Notifications. Each notification service entry creates a unique tag. If a task includes that tag, notifications are sent to that service whenever the task changes.

Non-browser notifications (email/webhooks/etc.) are dispatched asynchronously. If a send fails, the delivery status and an error summary are recorded on the notification event log (and in the application logs).

What triggers notifications

Notification routing (service tags)

  1. Create one or more notification services in your profile.
  2. Copy the generated notify:… tag for that service (tip: click the tag in the Notifications page to copy).
  3. Add that tag to any task you want routed to that service.
  4. If a task has multiple service tags, it will send to multiple services.

Notification message format

Notifications use this canonical text format: 

<CHANGE_ACTION>:<URL><TASK_NAME></URL> -<DUE_DATE> [<TAGS>]

The URL is the task's configured URL if present, otherwise it links to the in-app task editor.

Supported notification services

Each service type has a small configuration payload. You can create multiple entries per type (for example, multiple Gotify tokens or multiple webhooks).

Example service configuration payloads

These match the fields shown in the profile notifications UI and the /api/notifications/services endpoints. 

{
  "service_type": "gotify",
  "name": "Phone",
  "enabled": true,
  "config": {
    "base_url": "https://gotify.example.com",
    "token": "YOUR_APP_TOKEN",
    "priority": 5
  }
}
{
  "service_type": "ntfy",
  "name": "Personal",
  "enabled": true,
  "config": {
    "server_url": "https://ntfy.sh",
    "topic": "my-topic",
    "token": "OPTIONAL_BEARER_TOKEN",
    "priority": "high"
  }
}
{
  "service_type": "webhook",
  "name": "Automation",
  "enabled": true,
  "config": {
    "url": "https://example.com/webhook/timeboardapp",
    "secret": "OPTIONAL_SHARED_SECRET"
  }
}
{
  "service_type": "generic_api",
  "name": "Custom API",
  "enabled": true,
  "config": {
    "url": "https://api.example.com/v1/events",
    "method": "POST",
    "token": "OPTIONAL_BEARER_TOKEN",
    "headers": {
      "X-App": "timeboardapp"
    }
  }
}

Admin settings

Email

Email settings are configured in Admin → Email and stored in the database. The sample settings.yml can be used once to seed initial values, but runtime configuration is managed in the admin UI (or via the admin API).

SMTP Docker note: if TimeboardApp is running in a container, localhost/127.0.0.1 refers to the container itself. Use a hostname/IP that is reachable from inside the container (for example: an SMTP container service name on the same docker-compose network, or host.docker.internal when using Docker Desktop).

Push notifications (WNS)

Global WNS credentials are configured in Admin → Push Notifications. Users then add per-device channel_uri values in their own notification service entries.

Application logs

Logs are written to /data/logs (one file per day) with standard levels: DEBUG, INFO, WARN, ERROR. Retention and log level are configured in Admin → Logs.

Validation

Admins can run feature and security validation from Admin → Validation. The run writes a redacted, pasteable log under /data/validation by default.

API

Interactive API documentation is available at /docs (OpenAPI/Swagger UI).

Endpoint reference

All endpoints below are rooted at the same TimeboardApp base URL. Most endpoints require an API token.

/api/auth

/api/users

/api/tasks

/api/tags

/api/notifications

/api/admin

Authentication

Obtain a token with: 

curl -X POST -d "username=YOUR_USERNAME&password=YOUR_PASSWORD" \
  http://localhost:8000/api/auth/token

Use the returned token as: 

Authorization: Bearer <ACCESS_TOKEN>

Common API examples

Create a task:

curl -X POST http://localhost:8000/api/tasks/ \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pay rent",
    "due_date_utc": "2026-03-01T00:00:00Z",
    "tags": ["finance", "notify:u1:ntfy:abcd1234"]
  }'

List tasks (pending):

curl http://localhost:8000/api/tasks/?status=pending \
  -H "Authorization: Bearer <TOKEN>"

Create a notification service:

curl -X POST http://localhost:8000/api/notifications/services \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "ntfy",
    "name": "Phone",
    "enabled": true,
    "config": {
      "server_url": "https://ntfy.sh",
      "topic": "my-topic"
    }
  }'

List your notification services (and copy the generated tag):

curl http://localhost:8000/api/notifications/services \
  -H "Authorization: Bearer <TOKEN>"

List notification events:

curl http://localhost:8000/api/notifications/events?limit=50 \
  -H "Authorization: Bearer <TOKEN>"

Admin API examples

Admin endpoints require an admin user.

Update email settings (SMTP):

curl -X PUT http://localhost:8000/api/admin/email \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "smtp",
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "smtp_username": "user@example.com",
    "smtp_password": "YOUR_PASSWORD",
    "smtp_from": "TimeboardApp <timeboardapp@example.com>",
    "use_tls": true
  }'

Update email settings (SendGrid):

curl -X PUT http://localhost:8000/api/admin/email \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "sendgrid",
    "sendgrid_api_key": "YOUR_SENDGRID_API_KEY",
    "smtp_from": "TimeboardApp <timeboardapp@example.com>"
  }'

List log files:

curl http://localhost:8000/api/admin/logs/files \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

Read the tail of a log file:

curl "http://localhost:8000/api/admin/logs/files/timeboardapp-2026-02-20.log?max_lines=2000" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"