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 journey to create.

goal
string
required

1–4000 characters.

Maximum string length: 4000
personaId
string
required

An existing persona in this project.

sessionsPerTarget
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 journey.

A persona's task: what they are trying to accomplish, and across which targets. Launching one is POST /projects/{projectId}/journeys/{journeyId}/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 journey was authored under. Provenance only — nothing resolves through it at run time, and a journey created outside a swarm has none.

environmentIds
string[]
required

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

sessionsPerTarget
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 journey.