Browse docsupdate_goal
update_goal
Patches the wording, private details, or audience of a goal you own. Saving starts no search. Ending is a separate action.
Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false
When to use it#
Use only when asked to edit a goal's fields or sharing. To create one, use create_goal. To end one, use end_goal, or batch_end_goals for several. Resolve the exact goal and explain the audience for sharing changes.
An edit supplies only the fields the member wants changed. Omitted fields stay unchanged. Read the goal first and copy its opaque version unchanged as expectedVersion. Wording, private details, selected-group, visibility, and lifecycle changes invalidate older versions.
Inputs#
| Input | Required | Type | Description |
|---|---|---|---|
goalId | yes | string | The exact owned goal ID. |
text | no | string | Nonblank new wording, up to 2,000 characters. Omit to preserve wording. Empty or whitespace-only text is rejected and never ends a goal. |
audience | no | list of objects | Complete replacement selection and visibility, up to 100 distinct authorized groups. Each entry requires groupPublicId and visibility (visible or hidden). Omit to preserve it; [] makes it private. |
additionalContext | no | string | Complete replacement private details, up to 4,000 characters. Omit to preserve them; "" clears them. |
expectedVersion | yes | string | Opaque version copied unchanged from get_goal. |
Supply at least one of text, additionalContext, or audience. visible lets a group's members read the goal; hidden keeps that group's network selected for searches without showing the goal in that group. Keep confidential details in additionalContext, outside shared text. Goals for a fixed beneficiary remain private and their beneficiary cannot change. See Goals and audiences.
What each change does#
- Wording, private context, and selected-group changes advance
scopeVersionand cancel this goal's obsolete search. Other goals' searches continue. - Visibility-only changes save immediately without changing matching inputs or stopping a search.
- Saving starts no replacement search. Call
start_goal_searchseparately for an authorized search.
All supplied fields commit together. Validation, access, and version failures leave them unchanged. Obsolete workers cannot publish further results as current after the edit commits. Existing conversations remain attached to the goal.
Returns#
Success returns status, outcome, message, the canonical owned goal, and cancelledSearchIds. MCP also adds the goal's exact Gravity link. Saving starts no search. Read search state through get_goal_search, match summaries through list_goal_matches, and a selected assessment through get_goal_match.
| Outcome | Meaning |
|---|---|
saved | The requested changes were committed. |
no_change | All supplied changes already match current state; the goal was unchanged and no search started. |
goal has the base owned fields of get_goal, excluding Full’s matches page, captured inside the save transaction, including owner, private details, audience, beneficiary identity, authorship, lifecycle fields, and the committed opaque version. Authorship identifies the member who supplied a received goal; it never includes their private source goal. cancelledSearchIds identifies the obsolete searches cancelled by this edit. The receipt contains no search state, matches, or available groups. Later changes do not replace the committed receipt; a later read may show a newer revision.
Every save compares the supplied fields with current state. If they already match, the result is no_change, even when a supplied version is old, so repeating an edit is safe. A stale whole-goal version rejects an edit that would change state, including a visibility edit. An identical patch retains the current version.
Errors use the common contract. For a conflict, explain that the goal changed since the edit was prepared, inspect currentState, and prepare a new action only within the member's intent.
Examples#
Change only wording:
{
"goalId": "00000000-0000-4000-a000-000000000001",
"text": "Find design partners",
"expectedVersion": "00000000-0000-4000-8000-000000000901"
}
Example response (synthetic data):
{
"status": "success",
"outcome": "saved",
"message": "Goal saved.",
"goal": {
"id": "00000000-0000-4000-a000-000000000001",
"beneficiary": null,
"text": "Find design partners",
"additionalContext": "Synthetic private details",
"clarificationQuestion": null,
"scopeVersion": 2,
"suggestedByGravity": false,
"retiredAt": null,
"createdAt": "2026-10-09T00:00:00.000Z",
"endReason": null,
"authorship": null,
"version": "00000000-0000-4000-8000-000000000902",
"owner": {
"memberId": "00000000-0000-4000-a000-000000000003",
"name": "Synthetic member"
},
"isOwner": true,
"audience": [
{
"groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"name": "Synthetic founders",
"visibility": "hidden"
}
]
},
"cancelledSearchIds": [],
"link": "https://www.meetgravity.ai/dashboard/goals/00000000-0000-4000-a000-000000000001"
}