Goals

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Goal`goal`

A goal with progress, milestones, check-ins, and links.

goals_findFindthrough vritto_find

Read Goals: one goal by id, or goals filtered by status, text, priority, horizon, area, tag, owner, linked record or target date; type 'measurement' lists what Vritto can measure a goal from. Compact rows (health, progress, measuredBy) unless detail is 'full'. Cancelled goals are excluded.

Note: type 'measurement' lists what other modules can measure a goal by; use a listed moduleId and metricId as a goal's measure.

Field	Type	Description
type	one of goal, measurement	'goal' (default) or 'measurement': each module's metrics (id, label, shape, cadences, aims, an example), read before adding a measured goal.
id	string	Return just this goal, every field (check-ins, steps, the full why).
query	string	Free-text search over titles, whys, tags, and check-ins.
status	one of planned, active, paused, achieved, missed, cancelled	Filter by status.
priority	one of low, normal, high, urgent	Filter by priority.
horizon	one of weekly, monthly, quarterly, yearly, custom	Filter by horizon.
area	string	Filter by area.
tag	string	Filter by tag.
ownerPersonId	string	Only goals owned by this person ID.
linkedModuleId	string	Only goals linked to records of this module.
linkedEntityId	string	Only goals linked to this record ID (combine with linkedModuleId).
from	string	Only goals whose target date is on or after this date.
to	string	Only goals whose target date is on or before this date. ALWAYS pass from/to when the question concerns a period.
includeArchived	boolean	Include cancelled goals; default false.
detail	one of summary, full	Row shape: "summary" (default, compact rows with health and the measured value) or "full" (every field incl. check-ins, milestones, and habit log).
limit	integer	Max records to return (default 50 in summary mode).
goalId	string	Older name for id.

Example input

{
  "status": "active"
}

goals_addCreatethrough vritto_create

Add a goal. Only goal.title is required. Measured example: { title: "Read 24 books this year", kind: "target", measure: { moduleId: "books", metricId: "books_finished" }, targetValue: 24, startDate: "2026-01-01", targetDate: "2026-12-31" }. By-hand example: { title: "Write 50,000 words", kind: "target", startValue: 0, targetValue: 50000, unit: "words" }.

Field	Type	Description
goal*	object	Goal fields; only title is required.
goal.title*	string	Goal title.
goal.why	string	Reason this goal matters.
goal.status	one of planned, active, paused, achieved, missed, cancelled	Goal status; defaults to "active".
goal.priority	one of low, normal, high, urgent	Priority; defaults to "normal".
goal.kind	one of objective, key_result, habit, target	"target" (reach or stay under a number), "habit" (every day, week or month), or "objective" (steps or done).
goal.area	string	Area or domain.
goal.startDate	string	Start date YYYY-MM-DD.
goal.targetDate	string	Target date YYYY-MM-DD.
goal.measure	object
goal.aim	one of reach, limit	"reach" (default) or "limit" (stay at or under the target, e.g. spending).
goal.metricType	one of percent, number, currency, boolean	For a number the person updates: "number" (default), "currency" (unit = ISO code), or "percent".
goal.startValue	number	Starting value; for a measured level it defaults to today's reading.
goal.currentValue	number	Current value of a number the person updates.
goal.targetValue	number	Target; for a habit, the target per period (4 workouts a week).
goal.unit	string	Unit for a number the person updates, e.g. "kg", "books", or an ISO currency code.
goal.habitCadence	one of daily, weekly, monthly	Period of a "habit" goal; defaults to "daily".
goal.confidence	integer	Confidence from 0 to 100; defaults to 70.
goal.ownerPersonIds	list of string	Owner person IDs.
goal.tags	list of string	Tags.
goal.linkedRefs	list of object	Related records in other modules (they never move progress). Prefer goals_change ref / unlink for one change.
goal.milestones	list of object	Steps, or checkpoints with a targetValue.
goal.favorite	boolean	Mark the goal as a favorite.
goal.idempotencyKey	string	Stable dedupe key so a retried create does not duplicate the goal.

Example input

{
  "goal": {
    "title": "Run a half marathon",
    "kind": "target",
    "horizon": "quarterly",
    "targetDate": "2026-12-06",
    "metricType": "number",
    "startValue": 0,
    "targetValue": 21.1,
    "unit": "km"
  }
}

goals_changeUpdatethrough vritto_update

Change one goal by id: patch for fields, status (e.g. "achieved" when the person confirms), checkIn (note, confidence, progressValue for a number tracked by hand), habitDay to tick a tapped habit, milestoneId with status to tick a step, ref or unlink for a related record. Progress and health are recomputed by the server. Resolve the id with goals_find first.

Note: One goal by id: patch for fields; status, checkIn, habitDay, milestoneId with status, ref and unlink are its named changes. Progress and health are recomputed.

Field	Type	Description
id	string	The goal to change. Required.
patch	object	Goal fields to change; omitted fields are kept.
patch.title	string	Goal title.
patch.why	string	Reason this goal matters.
patch.status	one of planned, active, paused, achieved, missed, cancelled	Goal status; defaults to "active".
patch.priority	one of low, normal, high, urgent	Priority; defaults to "normal".
patch.kind	one of objective, key_result, habit, target	"target" (reach or stay under a number), "habit" (every day, week or month), or "objective" (steps or done).
patch.area	string	Area or domain.
patch.startDate	string	Start date YYYY-MM-DD.
patch.targetDate	string	Target date YYYY-MM-DD.
patch.measure	object
patch.aim	one of reach, limit	"reach" (default) or "limit" (stay at or under the target, e.g. spending).
patch.metricType	one of percent, number, currency, boolean	For a number the person updates: "number" (default), "currency" (unit = ISO code), or "percent".
patch.startValue	number	Starting value; for a measured level it defaults to today's reading.
patch.currentValue	number	Current value of a number the person updates.
patch.targetValue	number	Target; for a habit, the target per period (4 workouts a week).
patch.unit	string	Unit for a number the person updates, e.g. "kg", "books", or an ISO currency code.
patch.habitCadence	one of daily, weekly, monthly	Period of a "habit" goal; defaults to "daily".
patch.confidence	integer	Confidence from 0 to 100; defaults to 70.
patch.ownerPersonIds	list of string	Owner person IDs.
patch.tags	list of string	Tags.
patch.linkedRefs	list of object	Related records in other modules (they never move progress). Prefer goals_change ref / unlink for one change.
patch.milestones	list of object	Steps, or checkpoints with a targetValue.
patch.favorite	boolean	Mark the goal as a favorite.
patch.idempotencyKey	string	Stable dedupe key so a retried create does not duplicate the goal.
status	one of planned, active, paused, achieved, missed, cancelled, todo, in_progress, done	The goal's new status ('achieved' when the person confirms). With milestoneId, that step's status: todo, in_progress, done or cancelled.
milestoneId	string	A step's id from the goal's milestones; status then ticks or reopens that step.
checkIn	object	Goal check-in fields.
checkIn.date	string	Check-in date YYYY-MM-DD; defaults to today.
checkIn.summary	string	Progress summary: what happened since the last check-in.
checkIn.confidence	integer	Confidence from 0 to 100; defaults to 70.
checkIn.progressValue	number	New value of a number the person updates by hand; ignored for goals Vritto measures.
checkIn.nextStep	string	Next concrete step.
checkIn.blockers	list of string	Blockers.
habitDay	string	Toggle a tapped habit's completion for this day YYYY-MM-DD (today's date for 'I did it today'); the same day again undoes it. Not for habits Vritto measures.
ref	object	Relate a record in another module (deduped by moduleId + entityId); it never moves progress.
ref.moduleId*	string	Module ID of the related record.
ref.entityId*	string	Related record ID.
ref.label	string	Human-readable label.
ref.relation	one of supports, blocks, reference	"supports" (moves this goal, default), "blocks", or "reference" (context).
unlink	object	Remove one related record.
unlink.moduleId*	string	Module ID of the link to remove.
unlink.entityId*	string	Entity ID of the link to remove.
expectedRevision	integer	Optional revision guard; the write is rejected if the stored revision differs.
goalId	string	Older name for id.
goal	object	Older whole-goal form: the goal with its id; absent fields keep their stored values.
goal.id*	string
date	string	Older form of habitDay.
moduleId	string	Older form of unlink, with entityId.
entityId	string	Older form of unlink, with moduleId.

Example input

{
  "id": "goal_half",
  "patch": {
    "targetDate": "2027-03-31",
    "confidence": 70
  }
}

goals_removeDeletethrough vritto_delete

Delete one goal (marks it cancelled). Only for explicit deletion requests; a goal that is over is a goals_change status. Resolve the id with goals_find first.

Field	Type	Description
id	string	The goal to remove.
expectedRevision	integer	Optional revision guard; the write is rejected if the stored revision differs.
goalId	string	Older name for id.

Goals

Goalgoal

Goal`goal`