Skip to main content
PATCH
Update a journey

Authorizations

Authorization
string
header
required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId
string
required

ID of the hosted project that contains the server.

goalId
string
required

Goal ID, as returned by the project's goal list.

Body

application/json

Fields to change.

PATCH with a TRI-STATE, and the third state is the point: a field absent leaves it alone, present sets it, and null CLEARS it. There is no other way to say "stop fanning this goal out across environments and go back to its host targets".

iterations and maxTurns must be sent TOGETHER — they are one config object upstream, so a partial update would need a read-modify-write that could silently clobber a concurrent edit. Requiring both is a 400 you can fix rather than a lost update you never see.

name
string
Maximum string length: 200
goal
string
Maximum string length: 4000
environmentIds
string[] | null

A non-empty list to set, or null to clear and fall back to host targets.

Minimum array length: 1
serverAttachmentId
string | null

null clears the attachment.

hostIds
string[]
iterations
integer
Required range: 1 <= x <= 100
maxTurns
integer
Required range: 1 <= x <= 200

Response

The updated goal.

A persona's task: what they are trying to accomplish, and across which targets. Launching one is POST /projects/{projectId}/goals/{goalId}/runs.

id
string
required
projectId
string
required
name
string
required
goal
string
required

What the persona is trying to accomplish. This drives the whole run.

personaId
string
required
swarmId
string | null
required

The swarm container this goal was authored under. Provenance only — nothing resolves through it at run time, and a goal created outside a swarm has none.

environmentIds
string[]
required

Environments this goal fans out across. EMPTY on a host-pinned goal — that is a different execution model, not a goal with no targets.

iterations
integer | null
required

Sessions run against EACH target. Total sessions = targets × this.

maxTurns
integer | null
required
createdAt
number
required

Epoch milliseconds.

updatedAt
number
required

Epoch milliseconds.

serverAttachmentId
string

Legacy host-pinned grounding. Absent on an environment-based goal.

setupWrites
boolean

Whether prerequisite setup may create or modify workspace data before sessions run. Defaults to false.