---
title: "Draft personas with a model"
method: POST
path: "/projects/{projectId}/personas/generate"
tags: ["Swarms"]
---

# Draft personas with a model

`POST /projects/{projectId}/personas/generate`

Returns DRAFTS and persists nothing. That separation is deliberate: generation is the step most likely to produce something nobody wanted, and a route that both invented and saved would make "let me see what you'd suggest" indistinguishable from "fill my project with these".

It is also why there is no idempotency key — a call with no effect has nothing to de-duplicate, and offering one would imply the drafts are stable across retries when they are not.

**SPENDS.** This runs models on your organization's account and is metered two ways: a per-minute burst brake (429, retry in seconds) and your plan's daily budget (429, resets at UTC midnight). Both normally carry `Retry-After` — honor it when it is there, and back off on your own when it is not.

## Request body

- PersonaGenerateRequest — Exactly ONE grounding source: `serverAttachmentId` or `environmentId`. Sending both is a 400 — a request that is already confused about what it wants should not have a winner picked for it.
  - `serverAttachmentId` string
  - `environmentId` string
  - `journeyCount` integer — Journeys to draft per persona.
  - `personaCount` integer — Ask for a SLATE of N personas. Omitting it is not the same as `1`: it selects the legacy single-persona response shape, so a default would switch the response under a caller that only knows the other one.
  - `description` string — Free-text audience brief, forwarded verbatim into the prompt.
  - `existingPersonas` object[] — Personas you already have, so the model drafts different ones. A prompt hint, not a data feed — only the first few dozen are used.
    - `name` string, required
    - `role` string, required

## Response `200`

Draft personas and journeys.

- GenerationDrafts — DRAFTS. Nothing here is persisted — feed what you want to keep to `POST /projects/{projectId}/personas` or `POST /projects/{projectId}/journeys`. The shape depends on the request: `POST /personas/generate` returns `{persona, journeys}` without `personaCount` and `{personas: [{persona, journeys}]}` with it; `POST /journeys/generate` returns `{journeys}`.
  - `persona` PersonaDraft — A generated persona draft. Nothing is persisted until you create it.
    - `name` string, required
    - `role` string, required
    - `notes` string
  - `personas` object[]
    - `persona` PersonaDraft — A generated persona draft. Nothing is persisted until you create it.
      - `name` string, required
      - `role` string, required
      - `notes` string
    - `journeys` JourneyDraft[]
      - `name` string
      - `goal` string, required
      - `suggestedChecks` object[] — Deterministic checks the backend suggests. Only `toolCalledAtLeastOnce` is ever suggested — it is the one kind whose validity the grounding snapshot can prove, because the tool provably exists.
        - `type` 'toolCalledAtLeastOnce', required
        - `toolName` string, required
  - `journeys` JourneyDraft[]
    - `name` string
    - `goal` string, required
    - `suggestedChecks` object[] — Deterministic checks the backend suggests. Only `toolCalledAtLeastOnce` is ever suggested — it is the one kind whose validity the grounding snapshot can prove, because the tool provably exists.
      - `type` 'toolCalledAtLeastOnce', required
      - `toolName` string, required

## Other responses

- `400` — Malformed body or parameters.
- `401` — Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key.
- `403` — Key is valid but not allowed to do this.
- `404` — Unknown project, server, or resource.
- `429` — Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter.
- `500` — Something failed on MCPJam's side.

---

[API](https://skmtc.net/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.net/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mcpjam/mcpjam-api/revisions/d3adfe49fbbf/schema)