`save_goal`

Creates a goal, or changes or ends one you own.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

When to use it#

Only when you're asked to create, edit, share, hide, or end a goal.

Before saving, say which groups will read the goal.
Before ending one, say that its introduction chats will be archived.
Read the goal with get_goal first, and pass the versions it returns.

Inputs#

Input	Required	Type	Description
`goalId`	yes	string or null	`null` to create a goal. Otherwise, the ID of your goal.
`text`	yes	string	The goal, up to 2,000 characters. An empty string ends the goal, and so does text that's only spaces.
`selectedGroupPublicIds`	yes	list of strings	The complete list of groups to share with, up to 100. `[]` keeps the goal private. Include only groups you were asked to use.
`expectedScopeVersion`	yes	integer or null	`null` to create. Otherwise, `goal.scopeVersion` from your latest `get_goal`.
`hiddenGroupPublicIds`	no	list of strings	The complete list of selected groups to hide the goal from. Each must also be in `selectedGroupPublicIds`. Omit it to keep each group's current setting. Newly added groups start shown.
`additionalContext`	no	string	The complete private details, up to 4,000 characters. Omit it to keep the current ones.
`expectedContextRevisionId`	no	string	`goal.contextRevisionId` from your latest `get_goal`. Required when you pass `additionalContext` for an existing goal.
`requestId`	yes	string	A new UUID for this action. Reuse it only to retry this exact call.

Write text so the selected groups can read it comfortably, and put confidential specifics in additionalContext. Don't invent details or repeat the goal in the private details. See Goals and audiences.

What each change does#

Change	Effect
Create	Creates the goal, with your `requestId` as its ID, and starts a full search
Edit the wording or private details	Keeps the goal's ID and conversations, increases `scopeVersion`, stops any running search, and searches again
Change the selected groups	Keeps the goal's ID, increases `scopeVersion`, and searches networks not yet searched. Removing a group drops matches through members who are no longer covered.
Change only `hiddenGroupPublicIds`	Changes who reads the goal, not what's searched. `scopeVersion` stays the same and no search starts.
Save with no changes	Searches networks that are new or updated since the last search
Empty `text`	Ends the goal. Its introduction chats are archived and read-only, it leaves `list_goals`, and it can't be reopened.

While the goal has an open clarificationQuestion and the wording hasn't changed, saving doesn't start a search.

Returns#

{ "status", "message", "goalId", "scopeVersion", "matchingRunId" }

Message	Status	Meaning
"Goal saved. Open your goal to review its search."	`success`	Saved, and a search started. `matchingRunId` is the search.
"Goal saved."	`success`	Saved. No search started.
"Goal ended."	`success`	The goal ended.
"Your goal was saved, but its search could not be started. Retry the search in your goal."	`error`	Saved, but the search didn't start. Read the goal, then use `start_goal_matching` if you're asked to retry. Don't save again.
"This goal or its audience changed or is unavailable. Reload before saving."	`error`	Nothing was saved. The goal changed since you read it, it ended or isn't yours, a group isn't one you belong to, or this `requestId` was already used for a different call. Read the goal again and confirm before retrying with a new `requestId`.
"Read the current goal before saving."	`error`	The version arguments don't fit. For example, a new goal without `text`, an edit without `expectedScopeVersion`, or new private details without `expectedContextRevisionId`.
"A goal can only be hidden from groups it's shared with."	`error`	`hiddenGroupPublicIds` includes a group that isn't in `selectedGroupPublicIds`.
"Keep your goal under 2,000 characters." or "Keep private details under 4,000 characters."	`error`	Too long

Examples#

Create a goal shared with one group, with private details:

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"
}

Result:

json

{
  "status": "success",
  "message": "Goal saved. Open your goal to review its search.",
  "goalId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "scopeVersion": 1,
  "matchingRunId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}

Reword the goal and share it with a second group, hidden from that group's members, keeping the private details:

json

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

End a goal, after saying its chats will be archived:

json

{
  "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "text": "",
  "selectedGroupPublicIds": ["3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b"],
  "expectedScopeVersion": 4,
  "requestId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a"
}

Create and edit a goal walks through both.
Errors and limits covers retries with requestId.

save_goal

When to use it#

Inputs#

What each change does#

Returns#

Examples#

Related#

`save_goal`