Getting Started

1. Your instance

After self-hosting todoless, your API is available at /api/ on the published port (the default stack publishes port 7070, configurable with TODOLESS_PORT). Check it is alive:

curl http://YOUR_TODOLESS_HOST:7070/api/hook-health

→ {"ok": true}

2. Create your first account

The very first account on a fresh instance bootstraps the family and becomes its admin. Use /api/setup-status to see whether setup is still open, then register:

# Check setup state
curl http://YOUR_TODOLESS_HOST:7070/api/setup-status

# Bootstrap (first account)
curl -X POST http://YOUR_TODOLESS_HOST:7070/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "demo@example.com",
    "password": "correct-horse-battery",
    "passwordConfirm": "correct-horse-battery",
    "name": "Alex",
    "user_type": "family_member",
    "family_name": "Example Family",
    "language": "nl"
  }'

# Later family members join with an invite code
curl -X POST http://YOUR_TODOLESS_HOST:7070/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "password": "correct-horse-battery",
    "passwordConfirm": "correct-horse-battery",
    "name": "Sam",
    "user_type": "family_member",
    "invite_code": "ABC123XYZ789",
    "language": "nl"
  }'

3. Log in and get a session token

curl -X POST http://YOUR_TODOLESS_HOST:7070/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity": "demo@example.com", "password": "correct-horse-battery"}'

The response contains a token. Send it on every authenticated request:

curl http://YOUR_TODOLESS_HOST:7070/api/entries \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

4. Create your first task

curl -X POST http://YOUR_TODOLESS_HOST:7070/api/tasks \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Book dentist appointment", "priority": 2, "due_date": "2026-10-05"}'

Next steps

• Read the Authentication guide for personal API tokens.
• Browse the endpoint groups for the full contract.
• Download the OpenAPI spec for machine-readable definitions.