API Overview

API Overview

BRAIN 3.0 exposes a RESTful API via FastAPI. All endpoints are under the /api prefix, with a standalone /health endpoint at the root. The full interactive documentation (Swagger UI) is available at /docs when the API is running.

This page orients you to what's available. For endpoint-level detail — request/response schemas, status codes, and parameter types — use the /docs page.

---

Health Check

Method	Path	Purpose
GET	/health	Returns API status and database connectivity

Returns {"status": "healthy", "database": "connected"} when everything is working, or a 503 with "unhealthy" if the database is unreachable.

---

Entity CRUD

Standard create, read, update, delete operations for all seven pillar entities. Each entity follows the same pattern:

Method	Path	Purpose
POST	/api/{entity}	Create
GET	/api/{entity}	List (with filters)
GET	/api/{entity}/{id}	Get by ID (detail view with nested children)
PATCH	/api/{entity}/{id}	Partial update
DELETE	/api/{entity}/{id}	Delete

Domains — /api/domains

Life areas. CRUD only — domains are a simple organizational layer.

Goals — /api/goals

Enduring outcomes nested under domains.

List filters: domain_id, status (active, paused, achieved, abandoned)

Projects — /api/projects

Bounded efforts nested under goals.

List filters: goal_id, status (not_started, active, blocked, completed, abandoned)

Tasks — /api/tasks

Atoms of action with ADHD-aware metadata. Tasks have the richest filtering of any entity — all filters are composable (combine any subset in a single request):

Filter	Type	What It Does
project_id	UUID	Tasks in a specific project
standalone	bool	Tasks with no project (true) or with a project (false)
status	string	Filter by status (pending, active, completed, skipped, deferred)
cognitive_type	string	Filter by cognitive type
energy_cost_min / energy_cost_max	int	Energy cost range (1-5)
friction_min / friction_max	int	Activation friction range (1-5)
context_required	string	Filter by context (at_home, at_computer, etc.)
due_before / due_after	date	Due date range
overdue	bool	Tasks past due date and not completed/skipped

These filters are how Claude matches tasks to your current capacity — filtering by energy, friction, cognitive type, and context to surface what makes sense right now.

Tags — /api/tags

Cross-cutting labels for tasks. Tags have globally unique names (case-insensitive) with get-or-create behavior on POST.

Method	Path	Purpose
POST	/api/tags	Create or retrieve an existing tag
GET	/api/tags	List all tags
GET	/api/tags/{id}	Get a tag
PATCH	/api/tags/{id}	Update a tag
DELETE	/api/tags/{id}	Delete a tag
GET	/api/tags/{id}/tasks	List all tasks with this tag

Task-tag associations:

Method	Path	Purpose
GET	/api/tasks/{task_id}/tags	List tags on a task
POST	/api/tasks/{task_id}/tags/{tag_id}	Attach a tag to a task
DELETE	/api/tasks/{task_id}/tags/{tag_id}	Detach a tag from a task

Routines — /api/routines

Behavioral patterns with streak tracking. Routines have additional endpoints beyond standard CRUD:

Method	Path	Purpose
POST	/api/routines/{id}/complete	Mark a routine as completed (updates streak counters)
POST	/api/routines/{id}/schedules	Add a schedule entry (day, time, preferred window)
GET	/api/routines/{id}/schedules	List schedule entries
DELETE	/api/routines/{id}/schedules/{schedule_id}	Remove a schedule entry

List filters: domain_id, status (active, paused, retired), frequency

Note: Completing a routine via /complete updates the streak counter but does not create an activity log entry. See Architecture — Explicit Activity Logging for why this is intentional and what it means for reporting.

Check-ins — /api/checkins

State snapshots (energy, mood, focus). CRUD with list filtering.

List filters: checkin_type (morning, midday, evening, micro, freeform), context, logged_after, logged_before (date range)

Activity Log — /api/activity

Record of what happened and how it felt. Each entry can reference a task, routine, and/or check-in.

List filters: action_type, task_id, routine_id, logged_after, logged_before (date range), has_task, has_routine

---

Reports

Four read-only aggregation endpoints that power pattern recognition. All are under /api/reports.

Endpoint	What It Answers
GET /api/reports/activity-summary	How productive was this period? Total completions, skips, deferrals, duration, average energy delta, average mood.
GET /api/reports/domain-balance	Which life areas are getting attention and which are being neglected? Active goals, projects, pending tasks, overdue tasks, and days since last activity per domain.
GET /api/reports/routine-adherence	How consistently am I maintaining my routines? Completions vs. expected, adherence percentage, streak health, broken streak flags.
GET /api/reports/friction-analysis	Am I overestimating or underestimating friction? Predicted vs. actual friction by cognitive type, completion rates, energy impact.

Activity summary and routine adherence require after and before query parameters (datetime range). Friction analysis defaults to the last 30 days if no range is specified. Domain balance has no parameters — it reports current state.

These endpoints are designed for Claude to consume and interpret conversationally. Claude reads the numbers; you get the insight in plain language.