# Siga Siga

> A personal to-do list that a person shares with their AI agents (the name is Greek for “slowly, slowly”). This page tells an agent how to read and change tasks.

Two ways in, same data and same permissions:

1. MCP (preferred): Streamable HTTP server at https://sigasiga.dev/mcp
2. REST: JSON API at https://sigasiga.dev/api/v1

## Authentication

- MCP clients that support OAuth (Claude connectors, ChatGPT, Claude Code): add https://sigasiga.dev/mcp and sign in when prompted. Nothing else to configure.
- Everything else: a personal API key, created by the owner under Agents in the web app. Send it as `Authorization: Bearer siga_key_…` (or `X-API-Key`). The key's name is how your actions are attributed.

## Concepts

- Task ids are short numbers (`42`, shown as #42).
- status: `open`, `in_progress`, `done`. priority: `none`, `low`, `medium`, `high`.
- assignee: `me` (the human) or `agent`. Tasks assigned to `agent` are delegated work: set `in_progress`, comment with progress and results, then complete. If you need the human, comment and set assignee back to `me`.
- due: wall-clock in the owner's timezone, `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm`. On input you may send natural language ("tomorrow 5pm", "next friday") and the server resolves it.
- list: tasks live in a named list or in the Inbox (`list: null`). Writing an unknown list name creates the list.
- Quick capture: `text` on create is parsed like the app's input box. `Call mom tomorrow 6pm #family !high +Home @agent every week` sets due, tag, priority, list, assignee and repeat in one string.
- Every change is recorded in an activity trail with who made it.

## REST reference

All paths are under https://sigasiga.dev/api/v1. JSON in, JSON out. Add `?format=text` to GET /overview, /tasks and /tasks/{id} for a compact plain-text form that costs far fewer tokens.

| Method | Path | Purpose |
|---|---|---|
| GET | /overview | Current time in the owner's timezone, counts, what is overdue / due today / assigned to agents. Start here. |
| GET | /tasks | Search. Query params: `view` (today, overdue, upcoming, inbox, agent, all), `status` (active, open, in_progress, done, all), `list`, `tag`, `assignee`, `query`, `due_from`, `due_to`, `near` ("lat,lng" or place name), `radius_km`, `limit`. |
| POST | /tasks | Create one task (object body) or many (`{"tasks":[…]}`, up to 50). |
| GET | /tasks/{id} | One task with its activity trail. |
| PATCH | /tasks/{id} | Change any writable field. Only fields you send change. |
| POST | /tasks/{id}/complete | Mark done. Optional body `{"comment":"…"}`. Repeating tasks get their next occurrence. |
| POST | /tasks/{id}/reopen | Back to open. |
| DELETE | /tasks/{id} | Delete permanently. Prefer completing. |
| POST | /tasks/{id}/comments | `{"text":"…"}` |
| POST | /tasks/{id}/attachments | JSON `{"name","text"}` or `{"name","base64","content_type"}`; or raw bytes with `?name=file.png`. Max 10 MB. |
| GET | /tasks/{id}/attachments/{attachment_id} | Download a file. |
| DELETE | /tasks/{id}/attachments/{attachment_id} | Remove a file. |
| GET | /lists | Lists with open-task counts. |
| POST | /lists | `{"name","color"?}` |
| PATCH | /lists/{id} | `{"name"?,"color"?,"archived"?}` |
| DELETE | /lists/{id} | Delete a list; its tasks move to the Inbox. |
| GET | /activity | Recent changes, newest first. `since` (ISO time), `limit`. |
| GET | /me | Owner name, timezone, current local time, and who you are acting as. |

### Writable task fields

`title`, `notes` (markdown), `due`, `priority`, `list` (name or id, null = Inbox), `tags` (array, replaces), `links` (array of URL strings or {url,title}, replaces), `location` (place name to geocode, or {name,lat,lng}, null clears), `checklist` (array of strings or {title,done}, replaces), `assignee`, `repeat` ("daily", "weekly", "monthly", "yearly", "every N days|weeks|months|years", null stops), `status`. On create only: `text`.

### Examples

```bash
# What is on the plate?
curl -H "Authorization: Bearer $SIGASIGA_KEY" "https://sigasiga.dev/api/v1/overview?format=text"

# Capture in natural language
curl -X POST -H "Authorization: Bearer $SIGASIGA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Renew passport next friday #admin !high"}' https://sigasiga.dev/api/v1/tasks

# Structured create
curl -X POST -H "Authorization: Bearer $SIGASIGA_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Book flights","due":"2026-12-01","list":"Travel","checklist":["Compare prices","Check baggage rules"],"location":"Larnaca airport"}' \
  https://sigasiga.dev/api/v1/tasks

# Pick up delegated work, report back, finish
curl -H "Authorization: Bearer $SIGASIGA_KEY" "https://sigasiga.dev/api/v1/tasks?view=agent&format=text"
curl -X PATCH -H "Authorization: Bearer $SIGASIGA_KEY" -H "Content-Type: application/json" -d '{"status":"in_progress"}' https://sigasiga.dev/api/v1/tasks/42
curl -X POST  -H "Authorization: Bearer $SIGASIGA_KEY" -H "Content-Type: application/json" -d '{"comment":"Done. Summary attached."}' https://sigasiga.dev/api/v1/tasks/42/complete
```

### Errors

Non-2xx responses are `{"error":"<code>","message":"<what went wrong and how to fix it>"}`. 400 = fix the request, 401 = bad or missing token, 403 = not permitted (`forbidden`) or a plan limit reached (`limit_reached`), 404 = no such task/list, 429 = slow down (`rate_limited`; wait for the `Retry-After` header).

### Limits (free plan)

Up to 1,000 open tasks (5,000 including completed ones), 200 lists, 500 comments per task, 20 connected agents. Each task is at most 32 KB (notes up to 10,000 characters). Attachments: 10 MB each, 20 per task, 200 MB in total. Requests: about 120 a minute, 4 at a time. Prefer `?format=text` and narrow filters over repeatedly listing everything.

## MCP tools

get_overview, list_tasks, get_task, add_tasks, update_task, complete_task, add_comment, delete_task, list_lists, create_list, update_list, list_activity, attach_file, get_attachment. They take the same fields as the REST API and return compact text.
