Skip to main content
POST
Create 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.

Headers

Idempotency-Key
string

Retry-safe create key. Replaying the SAME key with the SAME body returns the original resource instead of creating a second one; reusing it with a DIFFERENT body is a 409.

Path Parameters

projectId
string
required

ID of the hosted project that contains the server.

Body

application/json

The goal to create.

goal
string
required

1–4000 characters.

Maximum string length: 4000
personaId
string
required

An existing persona in this project.

iterations
integer
required
Required range: 1 <= x <= 100
maxTurns
integer
required
Required range: 1 <= x <= 200
name
string
Maximum string length: 200
swarmId
string

Authoring provenance only — which swarm container this was made in.

environmentIds
string[]

The environments to fan out across. NON-EMPTY when present: [] reads as "these, naming none", and would silently fall back to something else.

Minimum array length: 1
serverAttachmentId
string

Legacy host-pinned grounding.

hostIds
string[]

Response

The created 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.