API Reference

Default: http://localhost:9746

POST /entries

Create an entry.

{
  "category": "dev",
  "title": "built auth flow",
  "bullets": ["oauth2 pkce", "token refresh"],
  "hours_est": 3,
  "date": "2026-04-13",
  "time": "14:30"
}

Field	Type	Required	Default	Validation
category	string	yes		non-empty
title	string	yes		non-empty
bullets	[]string	yes		at least one non-empty
hours_est	number	no	0	0–24
date	string	no	today	YYYY-MM-DD
time	string	no	now	HH:MM

Returns 201:

{"id": 42, "date": "2026-04-13"}

PUT /entries/{id}

Update an existing entry by ID. Accepts the same fields as POST.

curl -X PUT http://localhost:9746/entries/42 -d '{
  "category": "dev",
  "title": "updated title",
  "bullets": ["revised bullet"],
  "hours_est": 4,
  "date": "2026-04-13",
  "time": "14:30"
}'

Returns 200 with the updated entry.

GET /entries

List entries. Supports three query modes:

# single date (default: today)
GET /entries?date=2026-04-13

# date range (inclusive)
GET /entries?from=2026-04-01&to=2026-04-15

# date range with category filter
GET /entries?from=2026-04-01&to=2026-04-15&category=dev

Returns 200 with a JSON array of entries. Returns [] if no matches.

DELETE /entries/{id}

Remove an entry by ID.

Returns 200:

{"deleted": 42}

GET /schema

Returns field names, types, and descriptions. Agents can call this to self-discover the API without hardcoded instructions in their prompts.

{
  "endpoints": [
    {
      "method": "POST",
      "path": "/entries",
      "fields": [
        {"name": "category", "type": "string", "required": true, "description": "..."}
      ]
    },
    {"method": "PUT", "path": "/entries/{id}", "description": "..."},
    {"method": "GET", "path": "/entries", "description": "..."},
    {"method": "DELETE", "path": "/entries/{id}", "description": "..."},
    {"method": "POST", "path": "/goals", "description": "..."},
    {"method": "GET", "path": "/goals", "description": "..."},
    {"method": "POST", "path": "/strategies", "description": "..."},
    ...
  ]
}

POST /goals

Create a daily goal.

{
  "text": "implement oauth2 pkce",
  "date": "2026-04-14",
  "strategy_id": 1
}

Field	Type	Required	Default	Description
text	string	yes		Goal description
date	string	no	today	YYYY-MM-DD
strategy_id	number	no		Link to a strategic goal

Returns 201:

{"id": 1, "date": "2026-04-14"}

GET /goals

List goals for a date.

GET /goals?date=2026-04-14

Returns 200 with a JSON array. Each goal includes entry_ids if any entries are linked.

PUT /goals/{id}/done

Mark a goal complete. Optionally link entries:

{"entry_ids": [41, 42]}

PUT /goals/{id}/undo

Reopen a completed goal.

POST /goals/{id}/link

Link entries to a goal:

{"entry_ids": [41, 42]}

DELETE /goals/{id}

Delete a goal.

---

POST /strategies

Create a strategic goal.

{
  "title": "ship v2 auth",
  "description": "oauth2, token refresh, integration tests"
}

Field	Type	Required	Description
title	string	yes	Strategic goal title
description	string	no	Longer description

Returns 201:

{"id": 1, "title": "ship v2 auth"}

GET /strategies

List strategies. Filter by status:

GET /strategies?status=active

Status values: active, completed, archived. Omit for all.

GET /strategies/{id}

Strategy report with aggregated metrics:

{
  "id": 1,
  "title": "ship v2 auth",
  "status": "active",
  "goals_done": 2,
  "goals_total": 5,
  "total_hours": 12.5
}

PUT /strategies/{id}

Update strategy status:

{"status": "completed"}

DELETE /strategies/{id}

Delete a strategy. Unlinks goals but does not delete them.

---

GET /health

{"status": "ok"}