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"

Or install the typed client:

npm install @sharetodos/api-client
import { createApiClient } from '@sharetodos/api-client';

const client = createApiClient({ apiKey: 'sk_live_...' });

// Get all your lists
const lists = await client.lists.list();

// Add items to a list
await client.actions.add(['buy milk', 'call dentist'], 'my list');

// Mark items done
await client.actions.done(['buy milk'], 'my list');

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
GET /lists/:id/items Items in a list (?filter=open|done)
POST /lists/:id/items Add items directly to a list by ID

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/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"
}