Sign in
latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-15140179507.6 KB

d3adfe49fbbf

Swarms

Create a journey

Creates one journey: a persona pursuing a goal against one or more environments. To draft several with a model first, use POST /projects/{projectId}/journeys/generate — that route persists nothing.

personaId and swarmId must belong to THIS project. Naming one from another project is a 404, not a silent cross-project reference.

Creating a journey does not run it. Launch it with POST /projects/{projectId}/journeys/{journeyId}/runs.

post/projects/{projectId}/journeys

Headers

Idempotency-Keystring

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.

Request body

namestring
goalstring required

1–4000 characters.

personaIdstring required

An existing persona in this project.

swarmIdstring

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

environmentIdsstring[]

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

serverAttachmentIdstring

Legacy host-pinned grounding.

hostIdsstring[]
sessionsPerTargetinteger required
maxTurnsinteger required

Response

The created journey.

idstring required
projectIdstring required
namestring required
goalstring required

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

personaIdstring required
swarmIdstring nullable 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.

environmentIdsstring[] 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.

serverAttachmentIdstring

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

sessionsPerTargetinteger nullable required

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

maxTurnsinteger nullable required
createdAtnumber required

Epoch milliseconds.

updatedAtnumber required

Epoch milliseconds.