---
title: "List to-dos from documents"
method: GET
path: "/library/todos"
---

# List to-dos from documents

`GET /library/todos`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/library/todos`
- Auth: HTTP bearer

Every checklist item (`- [ ] text @who YYYY-MM-DD`) in the Markdown documents of the caller's Library: their own and those shared into their workspaces. Reads never persist an index. Follow next_cursor with the same caller, credential scope, source and filters, including today, even after an empty filtered page. Each page inspects at most 100 candidates, reads at most 25 Markdown documents and 8 MiB of saved bytes and returns at most 1,000 matching items. A document exceeding the byte budget is unavailable (413 for an exact source). The documents are the record; this list is derived from their saved versions. `mine` is what is assigned to one of the caller's handles, plus what is unassigned in their own documents. `@agent` marks an item for an agent (`forAgent`).

## Query parameters

- `cursor` string
- `scope` 'mine' | 'workspace'
- `status` 'open' | 'done' | 'all'
- `due` 'any' | 'overdue' | 'today' | 'week' | 'none'
- `source` string
- `today` string, date

## Response `200`

`todos` (id, text, done, assignee, forAgent, mine, due, overdue, line, source {id, name, owned, workspace}), `sources` (id, name, open, total), `today`, `truncated`, `next_cursor` (null when exhausted), `sources_partial`, `unavailable_sources` (currently authorized id/code), `unavailable_source_count` (also includes anonymous authority transport failures; revoked/unauthorized sources are omitted). Source counts are complete for each document read on this page within the requested mine/workspace scope; sources_partial means these are not full Library totals. A to-do id may be an opaque source/key locator; it grants no access and the same PATCH reauthorizes the current source.

- object

## Other responses

- `400`: Error — { error: { code, message } }
- `401`: Error — { error: { code, message } }
- `403`: Error — { error: { code, message } }
- `409`: Error — { error: { code, message } }
- `413`: Error — { error: { code, message } }
- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/library/todos/get.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)