Docsmeetgravity.ai
Guides / Create and edit a goal
View as Markdown

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.

1. Choose the audience#

Call list_groups and ask which groups should read the goal. 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. Confirm, then save#

Show both parts and the audience. When the member agrees, call save_goal with goalId: null, expectedScopeVersion: null, and a new requestId.

json
{
  "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 a search. You don't need to start one.

If the call times out without a result, retry once with the same requestId and identical arguments. You'll get the original result back, not a second goal.

4. Edit it later#

  1. Call get_goal to get the current scopeVersion, contextRevisionId, and selected groups.
  2. Call save_goal with the goal's ID, its current scopeVersion, the complete group list, and a new requestId.
  3. To change private details, pass all of them in additionalContext, plus expectedContextRevisionId. To keep them, leave both out.
json
{
  "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"
}

If the result is "This goal or its audience changed or is unavailable", the goal changed since you read it. Read it again, show the member what changed, and ask before saving with a new requestId.

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.