Generate encounter

Returns a randomized encounter appropriate for the specified party and environment. Pass in party context and optional constraints to get a fully-formed encounter object, including creatures, difficulty rating, and XP budget.

Endpoint

GET /v1/encounters/generate

Query parameters

Name	Type	Required	Description
party_level	integer	required	Average level of the party. Used to calibrate creature levels and XP budget. Range: 1–20.
environment	enum	required	The terrain or setting in which the encounter takes place. Determines creature pool and hazard types. Values: forest dungeon urban mountain ocean planar
party_size	integer	optional	Number of player characters in the party. Affects XP budget scaling. Range: 1–8. Default: 4
difficulty	enum	optional	Target difficulty tier for the encounter. Values: trivial low moderate severe extreme. Default: moderate
encounter_type	enum	optional	Category of encounter to generate. Use mixed to allow the API to blend types. Values: combat social hazard mixed. Default: combat
seed	integer	optional	Integer seed for reproducible results. Pass the same seed with the same parameters to regenerate an identical encounter. Useful for testing and session replay.

Example request

GET /v1/encounters/generate?party_level=5&party_size=4&environment=forest&difficulty=severe&encounter_type=combat

curl https://api.encounterforge.play/v1/encounters/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "party_level=5" \
  -d "party_size=4" \
  -d "environment=forest" \
  -d "difficulty=severe" \
  -d "encounter_type=combat"

Response

200 Success

{
  "encounter_id": "enc_7f3k29xq",
  "title": "Worg Pack Ambush",
  "description": "A pack of worgs has been stalking the party for the past mile, waiting for the trail to narrow before striking. They attack from both sides of the path.",
  "environment": "forest",
  "difficulty": "severe",
  "encounter_type": "combat",
  "creatures": [
    { "name": "Worg", "level": 2, "count": 4 },
    { "name": "Worg Alpha", "level": 5, "count": 1 }
  ],
  "xp_budget": 160,
  "seed": 83741
}

400 Error

{
  "error": {
    "code": "invalid_parameter",
    "param": "party_level",
    "message": "party_level must be an integer between 1 and 20. Received: 25."
  }
}

Response fields

Field	Type	Description
encounter_id	string	Unique identifier for the generated encounter. Prefixed with enc_. Use this to reference or retrieve the encounter later.
title	string	Short human-readable name for the encounter, suitable for display in a session tracker or GM notes.
description	string	Narrative setup for the encounter. Written from a GM perspective and intended to be read or paraphrased at the table.
environment	string	Echo of the environment parameter passed in the request.
difficulty	string	The difficulty tier the API targeted when generating this encounter. May differ slightly from the requested value if the creature pool required adjustment.
encounter_type	string	Echo of the encounter_type parameter. If mixed was requested, this field reflects the primary type the API selected.
creatures	array of objects	One or more creature groups that make up the encounter. Each object represents a distinct creature type.
creatures.name	string	Display name of the creature type.
creatures.level	integer	Creature level, used to calculate its contribution to the XP budget.
creatures.count	integer	Number of this creature type present in the encounter.
xp_budget	integer	Total XP value of all creatures in the encounter, calculated against the party’s level and size. Use this to verify difficulty or adjust rewards.
seed	integer	The seed used to generate this encounter. If no seed was provided in the request, the API assigns one. Pass this value back with the same parameters to reproduce the encounter exactly.