Swarms

Draft personas with a model

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.

POST

projects

{projectId}

personas

generate

Draft personas with a model

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serverAttachmentId": "<string>",
  "environmentId": "<string>",
  "journeyCount": 123,
  "personaCount": 6,
  "description": "<string>",
  "existingPersonas": [
    {
      "name": "<string>",
      "role": "<string>"
    }
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate"

payload = {
    "serverAttachmentId": "<string>",
    "environmentId": "<string>",
    "journeyCount": 123,
    "personaCount": 6,
    "description": "<string>",
    "existingPersonas": [
        {
            "name": "<string>",
            "role": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serverAttachmentId: '<string>',
    environmentId: '<string>',
    journeyCount: 123,
    personaCount: 6,
    description: '<string>',
    existingPersonas: [{name: '<string>', role: '<string>'}]
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'serverAttachmentId' => '<string>',
    'environmentId' => '<string>',
    'journeyCount' => 123,
    'personaCount' => 6,
    'description' => '<string>',
    'existingPersonas' => [
        [
                'name' => '<string>',
                'role' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate"

	payload := strings.NewReader("{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "persona": {
    "name": "<string>",
    "role": "<string>",
    "notes": "<string>"
  },
  "personas": [
    {
      "persona": {
        "name": "<string>",
        "role": "<string>",
        "notes": "<string>"
      },
      "journeys": [
        {
          "goal": "<string>",
          "name": "<string>",
          "suggestedChecks": [
            {
              "type": "toolCalledAtLeastOnce",
              "toolName": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "journeys": [
    {
      "goal": "<string>",
      "name": "<string>",
      "suggestedChecks": [
        {
          "type": "toolCalledAtLeastOnce",
          "toolName": "<string>"
        }
      ]
    }
  ]
}

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.

Body

application/json

Grounding source and slate size.

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.

Required range: 1 <= x <= 12

description

string

Free-text audience brief, forwarded verbatim into the prompt.

Maximum string length: 2000

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.

Show child attributes

Response

Draft personas and journeys.

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

object

A generated persona draft. Nothing is persisted until you create it.

Show child attributes

personas

object[]

Show child attributes

journeys

object[]

Show child attributes

⌘I

Draft personas with a model

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serverAttachmentId": "<string>",
  "environmentId": "<string>",
  "journeyCount": 123,
  "personaCount": 6,
  "description": "<string>",
  "existingPersonas": [
    {
      "name": "<string>",
      "role": "<string>"
    }
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate"

payload = {
    "serverAttachmentId": "<string>",
    "environmentId": "<string>",
    "journeyCount": 123,
    "personaCount": 6,
    "description": "<string>",
    "existingPersonas": [
        {
            "name": "<string>",
            "role": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serverAttachmentId: '<string>',
    environmentId: '<string>',
    journeyCount: 123,
    personaCount: 6,
    description: '<string>',
    existingPersonas: [{name: '<string>', role: '<string>'}]
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'serverAttachmentId' => '<string>',
    'environmentId' => '<string>',
    'journeyCount' => 123,
    'personaCount' => 6,
    'description' => '<string>',
    'existingPersonas' => [
        [
                'name' => '<string>',
                'role' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate"

	payload := strings.NewReader("{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/personas/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"serverAttachmentId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"journeyCount\": 123,\n  \"personaCount\": 6,\n  \"description\": \"<string>\",\n  \"existingPersonas\": [\n    {\n      \"name\": \"<string>\",\n      \"role\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "persona": {
    "name": "<string>",
    "role": "<string>",
    "notes": "<string>"
  },
  "personas": [
    {
      "persona": {
        "name": "<string>",
        "role": "<string>",
        "notes": "<string>"
      },
      "journeys": [
        {
          "goal": "<string>",
          "name": "<string>",
          "suggestedChecks": [
            {
              "type": "toolCalledAtLeastOnce",
              "toolName": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "journeys": [
    {
      "goal": "<string>",
      "name": "<string>",
      "suggestedChecks": [
        {
          "type": "toolCalledAtLeastOnce",
          "toolName": "<string>"
        }
      ]
    }
  ]
}

API Guides

Endpoints

Draft personas with a model

Authorizations

Path Parameters

Body

Response