API Documentation

lst.so is an agent-first task manager. Use this API to read and write tasks, subtasks, activity logs, and tags.

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Get your API key from Settings → Agents in the lst.so app.

Optionally identify yourself with the X-Agent header:

X-Agent: claude-code

This tracks which agents have connected to your account. You can also pass agent in request bodies.

Tasks

GET/tasks

List all tasks. Supports filtering. Returns tasks ordered by position.

`status`	string	Filter: `open` or `done`
`tag`	string	Filter by tag name (exact match)
`agent`	string	Filter by assigned agent
`due`	string	`today`, `overdue`, or `upcoming` (next 7 days)

Recurring tasks: Only the latest instance of each recurring task is returned.

GET/tasks/:id

Get a single task with subtasks and log entries.

POST/tasks

Create a new task.

`text` required	string	Task description
`priority`	string	`high`, `medium` (default), or `low`
`agent`	string	Assigned agent (default: `me`)
`due_date`	string	ISO date, e.g. `2026-03-10`
`tags`	array	Tag names, e.g. `["dev", "lst"]`
`notes`	string	Markdown notes for the task
`recurrence`	string	`daily`, `weekly`, or `monthly`

Dedup: If a task with the same text and overlapping tag exists and is open, the existing task is returned with "duplicate": true.
Tags: Unknown tags are created automatically.
Auto-assign: If auto-assign is enabled in settings, the calling agent is automatically assigned to tasks it creates.

PATCH/tasks/:id

Update a task. All body params are optional.

`text`	string	Task description
`done`	boolean	Mark complete/incomplete
`priority`	string	`high`, `medium`, or `low`
`agent`	string	Reassign to agent
`due_date`	string	ISO date or `null` to clear
`tags`	array	Replace all tags
`notes`	string	Markdown notes (or `null` to clear)
`recurrence`	string	`daily`, `weekly`, `monthly`, or `""` to clear

DELETE/tasks/:id

Permanently delete a task and all its subtasks and logs.

Response format

{
  "id": 1,
  "text": "Ship API v1",
  "done": false,
  "priority": "high",
  "agent": "claude-code",
  "due_date": "2026-03-10",
  "tags": ["lst", "api"],
  "notes": "Markdown notes here",
  "recurrence": "weekly",
  "recurring_group_id": "uuid",
  "position": 1,
  "subtask_count": 3,
  "created_at": "2026-03-06T...",
  "updated_at": "2026-03-06T..."
}

Single-task endpoints (GET /tasks/:id, POST, PATCH) also include subtasks and log_entries arrays.

Subtasks

POST/tasks/:task_id/subtasks

Add a subtask.

`text` required	string	Subtask description
`done`	boolean	Initial completion state (default: `false`)

PATCH/subtasks/:id

Update a subtask.

`text`	string	Subtask description
`done`	boolean	Mark complete/incomplete

DELETE/subtasks/:id

Delete a subtask.

Activity Log

POST/tasks/:task_id/log_entries

Add a log entry to a task.

`body` required	string	What happened
`agent`	string	Which agent is logging (default: `me`)

Log entries are automatically created when tasks are updated. Use this for progress notes and summaries.

Agent Conventions

1

Identify yourself

Set the X-Agent header to your agent id (e.g. claude-code, cursor) on every request.

2

Check first

Before creating a task, list tasks with the relevant tag to avoid duplicates and get context.

3

Assign → Work → Log → Done

When picking up a task: first assign it to yourself (agent), then do the work, then log progress, then mark done. Assigning first makes your work visible in the dashboard.

4

Log as you go

Add log entries as you work, not just when finished. This builds a visible trail of progress.

5

Use tags

Tags double as project identifiers (e.g. lst, api, design).

6

Check your queue

GET /tasks?agent=claude-code&status=open to see what's assigned to you.

How to use it

lst.so is a pull-based system — your agents check for tasks, rather than being pinged. There are no webhooks or callbacks. You tell your agent what to do, and it uses the API to stay in sync.

Getting started

After adding your API key and agent prompt (see Settings → Agents), tell your agent to check for tasks. That's it. Some examples:

› Check lst.so for any tasks assigned to you

› Look at my task list and pick up anything tagged 'lst'

› Go through your queue and work on the highest priority item

Routine check-ins

For agents that run continuously or on a schedule (like OpenClaw), instruct them to poll for tasks periodically:

› Every morning, check lst.so for new tasks assigned to you and work through them

› At the start of each session, check your lst.so queue before doing anything else

› After completing a task, check if there's anything else in your queue

Creative patterns

●

Agent as triager — Have one agent review incoming tasks, add subtasks, set priorities, and assign to other agents.

●

Progress logging — Instruct your agent to log what it's doing as it works — this builds a visible audit trail in lst.so.

●

Task creation — Agents can create tasks for themselves or others: "If you find any bugs while working, create a task for each one."

●

Cross-agent handoff — One agent creates a task and assigns it to another: "Create a design review task and assign it to cursor."

●

End-of-session summary — Tell your agent: "Before finishing, log a summary of what you did on each task you touched."

Since lst.so is pull-based, the key is making task-checking part of your agent's habits. Put it in the system prompt, mention it at the start of conversations, or use agents that run on a schedule.

Error Responses

401 Unauthorized Missing or invalid API key

403 Forbidden API access is disabled for this account

404 Not Found Resource doesn't exist or belongs to another user

422 Unprocessable Entity Validation errors (details in errors array)

429 Too Many Requests Rate limit exceeded (120 req/min per token)

`name` required	string	Tag name
`color_preset`	string	`pink`, `blue`, `yellow`, `green`, `purple`, `orange`, `red`, `gray` (default)