Goals and audiences

A goal is an outcome you want help with. You decide who reads it, and you can keep some of it private.

Ownership#

Each goal belongs to the member who wrote it. You can have several goals at once, each with its own audience.

	Goal owner	Another member who can read the goal
Read the goal	Yes	Yes, through a group it's shared with
Read its private details	Yes	No
Read its matches and start a search	Yes	No
Edit, share, hide, or end it	Yes	No

Audience#

A goal is read by the members of the groups its owner selects. Choose groups deliberately, and only the ones the owner asked for.

No groups: the goal is private. Gravity still searches the owner's own Rolodex for it.
One or more groups: members of those groups can read it, and Gravity searches their networks too.
Joining a group never adds it to your existing goals.

Goal text and private details#

A goal has two parts.

Part	Field	Who reads it	What belongs there
The goal	`text`	The selected groups	The outcome and the kind of person who could help, in words you're comfortable having those groups read
Private details	`additionalContext`	Only you. Gravity uses them to find matches.	Confidential specifics, such as prices, revenue, customer or member counts, named people or companies, internal plans, and what has or hasn't worked

For example:

Private details never appear to another member: not on the goal page, in their Gravity assistant, in a shared conversation, or in an introduction note.

Hidden groups#

You can hide a goal from a group you share it with. Gravity still searches that group's networks, but its members don't read the goal there. A member of that group reads it only through another group it's shown in, or once you open a conversation with them about it or ask them for an introduction.

Members never learn that a goal is hidden from a group. Only you see which groups it's hidden from. Hiding a goal changes who reads it, not what's searched, and it can't take back what someone already read.

Versions#

Every goal has two version values. Writes pass back the values you most recently read, so a change made somewhere else in the meantime is rejected instead of overwritten.

Value	Field	Changes when
Scope version	`scopeVersion`	The wording, private details, or selected groups change
Context revision	`contextRevisionId`	The wording or private details change

Read the goal with get_goal before every write, and again after it.

Ending a goal#

Ending a goal archives its introduction chats, which become read-only. An ended goal can't be reopened. Write a new goal instead.

Request IDs#

save_goal and start_goal_matching take a requestId: a UUID that your agent generates for each action. If a call fails before you get a result, retry it with the same requestId and identical arguments. Gravity returns the original result instead of repeating the change. Use a new requestId for every new action.