AI API

All AI endpoints require authentication.

POST /ai/parse_task

Parse natural language into structured task fields using Claude Haiku.

Auth required: Yes

Request body:

{
  "text": "renew passport in 3 months, remind me a week before",
  "user_date": "2026-05-26"
}

Response (200):

{
  "task": {
    "title": "Renew passport",
    "due_date": "2026-08-26",
    "category": "Documents",
    "repeat_interval_months": null,
    "reminder_days": [7]
  },
  "usage": {
    "ai_tasks_used": 3,
    "ai_tasks_limit": 5,
    "ai_tasks_remaining": 2,
    "subscription_tier": "free"
  }
}

Errors:

Status	Cause
400	Text is empty
403	AI usage limit reached
422	Parse failed

curl -X POST http://localhost:3000/api/v1/ai/parse_task \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"renew passport in 3 months","user_date":"2026-05-26"}'

---

POST /ai/edit_task

Parse a natural language edit instruction against the user's current tasks.

Auth required: Yes

Request body:

{
  "text": "move dentist to next Friday",
  "user_date": "2026-05-26"
}

Response (200):

{
  "edit": {
    "task_id": 5,
    "task_title": "Dentist appointment",
    "changes": {
      "due_date": "2026-05-29"
    }
  },
  "usage": {
    "ai_tasks_used": 4,
    "ai_tasks_limit": 200,
    "ai_tasks_remaining": 196,
    "subscription_tier": "pro"
  }
}

Errors:

Status	Cause
400	Text is empty
403	AI usage limit reached
422	Could not parse edit instruction

curl -X POST http://localhost:3000/api/v1/ai/edit_task \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"move dentist to next Friday","user_date":"2026-05-26"}'

---

GET /ai/usage

Get current AI usage stats without performing any action.

Auth required: Yes

Response (200) -- Free tier:

{
  "usage": {
    "ai_tasks_used": 3,
    "ai_tasks_limit": 5,
    "ai_tasks_remaining": 2,
    "subscription_tier": "free"
  }
}

Response (200) -- Family tier with household:

{
  "usage": {
    "ai_tasks_used": 3,
    "ai_tasks_limit": 200,
    "ai_tasks_remaining": 180,
    "subscription_tier": "family",
    "household_pool_used": 20,
    "daily_used": 1,
    "daily_limit": 3,
    "pool_depleted": false
  }
}

Response (200) -- Pro tier:

{
  "usage": {
    "ai_tasks_used": 15,
    "ai_tasks_limit": 200,
    "ai_tasks_remaining": 185,
    "subscription_tier": "pro"
  }
}

TIP

Pro users with ai_tasks_limit: null and ai_tasks_remaining: null are grandfathered users with unlimited access.

curl http://localhost:3000/api/v1/ai/usage \
  -H "Authorization: Bearer <token>"

---

GET /ai/suggestions

Get proactive task suggestions for the home screen.

Auth required: Yes

For users with fewer than 5 tasks, returns curated starter suggestions (no AI call, no usage charge). For users with 5+ tasks, uses Claude Haiku to suggest complementary tasks (costs 1 AI credit).

Response (200):

{
  "suggestions": [
    {
      "title": "Schedule annual eye exam",
      "category": "Health",
      "reason": "You have dental and doctor tasks but no eye care"
    }
  ],
  "usage": {
    "ai_tasks_used": 5,
    "ai_tasks_limit": 200,
    "ai_tasks_remaining": 195,
    "subscription_tier": "pro"
  }
}

curl http://localhost:3000/api/v1/ai/suggestions \
  -H "Authorization: Bearer <token>"

---

POST /ai/transcription_token

Generate a temporary Deepgram API key for client-side voice transcription.

Auth required: Yes

Response (200):

{
  "token": "dg_temp_abc123...",
  "expires_at": "2026-05-26T10:10:00Z"
}

The token has a 10-minute TTL and is tagged with the user's ID.

Errors:

Status	Cause
503	Deepgram API unavailable

curl -X POST http://localhost:3000/api/v1/ai/transcription_token \
  -H "Authorization: Bearer <token>"