sharetodos API v1

Build with sharetodos

A simple REST API for managing todo lists. Add items by email, SMS, Slack, or HTTP — everything lands in the same list.

Quick start

Create an API key at sharetodos.com/developers, then make your first request:

curl https://api.sharetodos.com/v1/lists \
  -H "X-API-Key: sk_live_your_key_here"

Add an item to a list:

curl -X POST https://api.sharetodos.com/v1/actions/add \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"items": ["buy milk", "call dentist"], "list": "Shopping"}'

Base URL

https://api.sharetodos.com/v1

All requests must be made over HTTPS. The API returns JSON for all responses.

Endpoints

Lists

GET /lists All lists you own or are a member of
POST /lists Create a list
GET /lists/:id Get a specific list
DELETE /lists/:id Delete a list
GET /lists/:id/items Items in a list (?filter=open|done)
POST /lists/:id/items Add items directly to a list by ID

Items

PATCH /items/:id Update an item (done, priority)
DELETE /items/:id Delete an item

Actions

Action endpoints handle all domain logic — they resolve lists by name, apply the profanity filter, and keep an audit trail for undo.

POST /actions/add Add items (resolves list by name)
POST /actions/done Mark items done (fuzzy match)
POST /actions/undone Unmark done items
POST /actions/clear Archive all completed items
POST /actions/undo Reverse the last action
POST /actions/priority Toggle priority on items (fuzzy match)
POST /actions/share Get the share URL and token
POST /actions/invite Invite a user to a list

Profile

GET /me Current user and active scopes

Response format

Every response uses a consistent envelope:

{
  "data": { ... },  // null on error
  "error": null       // string on error
}

Error example:

{
  "data": null,
  "error": "Insufficient scope: items:write"
}