Enrichment

Toto tasks aren't just one-line strings. Every item supports Markdown descriptions, sub-lists, priority levels, category tags, due dates, and arbitrary metadata. This guide covers all the enrichment features and how to use them effectively.

See it in action →

Markdown Descriptions

Every task has an expandable description field that supports full Markdown. Descriptions are rendered server-side and displayed in the expandable card UI.

Use descriptions for:

Implementation notes and approach
Links to related resources
Acceptance criteria
Code snippets or examples

curl -s -X POST "https://toto.up.railway.app/api/lists/rDJpQekZ/items" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Add OAuth middleware",
    "description": "## Approach\n\nUse authlib for Google OAuth. Steps:\n\n1. Configure OAuth client credentials\n2. Add redirect route at `/auth/callback`\n3. Create session cookie on successful auth\n\n## Notes\n\n- Use httponly cookies for security\n- Expiry: 30 days default, configurable via env var"
  }'

On the dashboard, click a task (or press e in VIM mode) to expand the card and see the rendered description.

Status Lifecycle

Every item has a status that controls its position in the workflow and its visual appearance on the dashboard.

Status	Dashboard Display	Meaning
`pending`	Default card	Waiting to be started
`in_progress`	Glowing card	Actively being worked on
`done`	Completion animation, then hidden	Finished
`blocked`	Red indicator	Waiting on an external dependency
`deferred`	Dimmed card	Postponed, not forgotten

Typical Flow

pending -> in_progress -> done

Use blocked when waiting on someone else or an external event. Use deferred for tasks you'll do later but don't want cluttering the active view.

API

# Set to in_progress
curl -s -X POST "https://toto.up.railway.app/api/items/px6K4KkE/status" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

When marking an item done, the server records completed_at (timestamp) and completed_by (the device or API key name that made the request).

Sub-Lists

Any task can have a child sub-list. This enables hierarchical task breakdown -- a parent task like "Add authentication" can have sub-tasks like "Configure OAuth", "Create user model", "Write tests".

Creating a Sub-List

curl -s -X POST "https://toto.up.railway.app/api/items/px6K4KkE/sublist" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Auth Sub-tasks"}'

If name is omitted, the sub-list inherits the parent item's task text.

Auto-Complete Cascade

When all items in a sub-list are marked done, the parent item is eligible for auto-completion. This cascade works bottom-up -- completing the last sub-task can trigger the parent to complete, which can trigger its parent, and so on.

Viewing Sub-Lists

curl -s "https://toto.up.railway.app/api/items/px6K4KkE/sublist" \
  -H "Authorization: Bearer toto_your_token"

Returns the sub-list and all its items. On the dashboard, items with sub-lists show a sub-list indicator that you can click to expand.

Depth Limit

Sub-lists are capped at 2 levels deep. A list can have sub-lists, and those sub-lists can have items, but items in sub-lists cannot have their own sub-lists.

Priority Levels

Items have 4 priority levels:

Level	Name	Display
0	None	No indicator
1	Low	Subtle indicator
2	Medium	Yellow indicator
3	High	Red indicator

Priority affects sort order when using ?sort=priority -- higher priority items appear first.

curl -s -X POST "https://toto.up.railway.app/api/items/px6K4KkE/edit" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"priority": 3}'

Due Dates

Optional ISO 8601 dates. Filterable via the API:

# Items due this week
curl -s "https://toto.up.railway.app/api/lists/rDJpQekZ/items?due_before=2026-04-12" \
  -H "Authorization: Bearer toto_your_token"

# Overdue items
curl -s "https://toto.up.railway.app/api/lists/rDJpQekZ/items?due_before=2026-04-06&status=pending" \
  -H "Authorization: Bearer toto_your_token"

Set via:

curl -s -X POST "https://toto.up.railway.app/api/items/px6K4KkE/edit" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"due_date": "2026-04-15"}'

Metadata

The metadata field is an arbitrary JSON object (10KB cap) attached to each item. It's used primarily by the semantic reconciliation engine (see Task Metadata), but you can use it for any structured data.

The toto_ prefix is reserved for system keys. Don't use it for custom fields.

Batch Operations

All batch endpoints accept up to 50 items per request.

Batch Create

curl -s -X POST "https://toto.up.railway.app/api/lists/rDJpQekZ/items/batch" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"task": "Task 1", "priority": 3, "category": "backend"},
    {"task": "Task 2", "priority": 2, "category": "frontend"},
    {"task": "Task 3", "priority": 1, "category": "test"}
  ]}'

Batch Status Update

curl -s -X PATCH "https://toto.up.railway.app/api/batch/items/status" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"updates": [
    {"id": "px6K4KkE", "status": "done"},
    {"id": "yBWXbGDr", "status": "done"}
  ]}'

Batch Delete

curl -s -X POST "https://toto.up.railway.app/api/batch/items/delete" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"item_ids": ["px6K4KkE", "yBWXbGDr"]}'

All batch endpoints return {"succeeded": [...], "failed": [...]} so you can handle partial failures.

The Card UI

On the dashboard, items are displayed as cards within list columns. Each card shows:

Task text
Category chip (colored by category name)
Priority badge (if priority > 0)
Due date (if set)
Printed flag (if printed)
Sub-list indicator (if the item has a child list)
Expand arrow (if description or metadata exists)

Click a card (or press e in VIM mode) to expand it and see:

Rendered Markdown description
Full metadata
Sub-list contents (if any)
Completion timestamp and device name (if done)