Create and edit a goal

Create a goal with the right audience and private details, then change it safely. Do this only when you're asked to.

This is the agent workflow. The member guide gives examples of what to ask.

1. Choose the audience#

Use list_groups to resolve groups the member named. Ask only when the requested audience is ambiguous. The default is none, which keeps the goal private.

Say plainly who will read it before saving. For example: "Founders dinner's 7 members will see this goal."

2. Write the two parts#

• text is the goal the selected groups read: the outcome and the kind of person who could help, in words the member is comfortable sharing with those groups.
• additionalContext is the private details: confidential specifics that help Gravity find matches, read only by the member.

Don't invent details, and don't repeat the goal in the private details. See Goals and audiences.

3. Save the requested action#

Show the wording and audience. A clear request authorizes that action; ask only for a missing consequential choice. Call save_goal with goalId: null, expectedScopeVersion: null, and a new requestId.

{
  "goalId": null,
  "text": "Meet seed investors who back developer tools.",
  "selectedGroupPublicIds": ["3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b"],
  "expectedScopeVersion": null,
  "additionalContext": "Raising $2M at a $12M cap. 40 paying teams, $18k monthly revenue. Two angels committed.",
  "requestId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}

Saving starts no search. Call start_goal_matching separately when the member asked to search.

If the call times out without a result, retry once with the original requestId and identical arguments. This returns no_change if the requested state is already present, or version_conflict with current state if the goal has changed. Then read the goal, whose ID is the original request ID. Follow Errors and limits.

4. Edit it later#

1. Resolve the exact owned goal. Read get_goal when you need its current wording, audience, private details, or a version precondition.
2. Supply only fields the member asked to change and a new requestId. Omitted fields stay unchanged; a supplied audience is the complete replacement list.
3. An optional expectedVersion constrains the edit to the complete state you read. Optional scope/context versions constrain matching inputs. No prior read is universally required.

{
  "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "text": "Meet Series A investors who back developer tools.",
  "selectedGroupPublicIds": ["3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b"],
  "expectedScopeVersion": 3,
  "requestId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
}

For version_conflict, the edit changed nothing. Read the goal again, explain any relevant concurrent change, and prepare a revised action with current versions and a new requestId. Ask only if the revised action needs a consequential choice the member has not authorized.

Keep private details private#

Never copy additionalContext into the goal's text, a message to a group, or a note to a connector, unless the member asks for that exact detail to be shared.

Version checks and retries#

goal.version is an opaque token for complete editable state, including visibility. scopeVersion changes when matching inputs change; contextRevisionId identifies wording/private details. These serve optional preconditions and describe search inputs.

On retry, matching supplied fields return no_change; an already-applied request whose desired state now differs returns version_conflict and current state. Explain the present state and reconcile the member's intent before preparing a new action. Use a new request ID for changed arguments. See Errors and limits.

An explicitly empty text ends a goal and archives its introduction chats. Never send empty or whitespace-only wording for an ordinary edit. Ending is irreversible and requires the member's explicit request; the goal can't be reopened.