API Reference

Complete reference for the Monster Gaming AI Gateway — OpenAI-compatible endpoints built for game developers.

Introduction

The Monster Gaming API provides AI capabilities purpose-built for games: NPC dialogue with persistent memory, discipline-specific expert routing, 59 models across 10 providers, and built-in game state management. The API is OpenAI-compatible — any OpenAI SDK works out of the box.

Quick start: Get a free API key with $5 credit at monstergaming.ai/signup — no credit card required. Then make your first API call in under 60 seconds.

Base URL

All API requests use the following base URL:

https://api.monstergaming.ai

For example, a chat completion request goes to https://api.monstergaming.ai/v1/chat/completions.

Authentication

Authenticate using a Bearer token in the Authorization header. API keys are issued when you create an account.

API Key Format

Prefix	Environment	Description
mg_live_	Production	Live API key — billed to your account
mg_test_	Sandbox	Test key — no billing, rate-limited to 5 req/min

Request Header

Authorization: Bearer mg_live_abc123def456...

Security: API keys are hashed at rest — we cannot recover them. Store your key securely. If compromised, rotate it immediately via the portal or POST /portal/api/keys/rotate.

Personal Access Tokens

For portal integrations, you can also use Personal Access Tokens (PATs) prefixed with mg_pat_. PATs authenticate against your developer account and have the same permissions as your API key.

Magic Link Login

POST /v1/auth/email Public

Send a magic link to the specified email address. Returns a success response regardless of whether the email exists (prevents enumeration).

GET /v1/auth/verify Public

Verify a magic link token (passed as ?token= query parameter). On success, sets a session cookie and redirects to the portal.

Rate Limiting

Rate limits are enforced per API key and vary by tier. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Tier	Requests/min	Daily Cap
Free	10	$5.00
Pay-as-you-go	30	$5.00
Starter	60	$10.00
Pro	300	$50.00
Studio	1,000	$200.00
Enterprise	Custom	Custom

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716345600
Retry-After: 30

Tip: All official SDKs handle rate limiting with automatic exponential backoff. If you hit limits frequently, consider upgrading your tier at monstergaming.ai/pricing.

Error Handling

All errors return a consistent JSON structure with machine-readable codes and human-readable remediation guidance.

Error Response

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded for starter tier (60 req/min).",
    "code": "RATE_LIMITED",
    "is_retryable": true,
    "retry_after": 30,
    "reset_at": "2026-05-22T12:00:00.000Z",
    "remediation": "Implement exponential backoff. SDKs handle this automatically."
  }
}

See the Error Codes section for a complete list.

Chat Completions

POST /v1/chat/completions Auth Required

Create a chat completion. OpenAI-compatible — drop-in replacement for any OpenAI SDK.

Request Body

Parameter	Type		Description
model	string	required	Model identifier. Use `monster-gpt` for automatic discipline routing, or specify a model directly (e.g. `deepseek-chat`, `claude-sonnet-4-6`).
messages	array	required	Array of message objects with `role` (`system`, `user`, `assistant`, `tool`) and `content` fields.
max_tokens	integer	optional	Maximum tokens in the response (1–128,000). Defaults to model maximum.
temperature	number	optional	Sampling temperature (0–2). Lower = more deterministic. Default: 1.
stream	boolean	optional	If `true`, returns a Server-Sent Events stream. Default: `false`.
npc_id	string	optional	Associate this completion with an NPC thread for persistent conversation memory.
npc_template	string	optional	Use a pre-built NPC personality template (e.g. `merchant`, `villain`). See NPC Templates.
player_id	string	optional	Player identifier for per-player NPC memory isolation.
response_style	string	optional	NPC response verbosity: `terse`, `normal`, `verbose`, or `dramatic`.
allow_fallback	boolean	optional	If `true`, automatically route to a fallback model when the primary is unavailable.

Code Examples

curl -X POST https://api.monstergaming.ai/v1/chat/completions \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "You are a grumpy dwarf blacksmith in a fantasy RPG."},
      {"role": "user", "content": "Can you forge me a legendary sword?"}
    ],
    "max_tokens": 150,
    "temperature": 0.8
  }'

from openai import OpenAI

client = OpenAI(
    api_key="mg_live_YOUR_KEY",
    base_url="https://api.monstergaming.ai/v1"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You are a grumpy dwarf blacksmith in a fantasy RPG."},
        {"role": "user", "content": "Can you forge me a legendary sword?"}
    ],
    max_tokens=150,
    temperature=0.8
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "mg_live_YOUR_KEY",
  baseURL: "https://api.monstergaming.ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "You are a grumpy dwarf blacksmith in a fantasy RPG." },
    { role: "user", content: "Can you forge me a legendary sword?" },
  ],
  max_tokens: 150,
  temperature: 0.8,
});

console.log(response.choices[0].message.content);

using OpenAI;
using OpenAI.Chat;

var client = new ChatClient(
    model: "deepseek-chat",
    credential: new ApiKeyCredential("mg_live_YOUR_KEY"),
    options: new OpenAIClientOptions {
        Endpoint = new Uri("https://api.monstergaming.ai/v1")
    }
);

var response = await client.CompleteChatAsync(
    new ChatMessage[] {
        new SystemChatMessage("You are a grumpy dwarf blacksmith in a fantasy RPG."),
        new UserChatMessage("Can you forge me a legendary sword?")
    },
    new ChatCompletionOptions { MaxOutputTokenCount = 150, Temperature = 0.8f }
);

Console.WriteLine(response.Value.Content[0].Text);

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("mg_live_YOUR_KEY")
    config.BaseURL = "https://api.monstergaming.ai/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "deepseek-chat",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "You are a grumpy dwarf blacksmith in a fantasy RPG."},
                {Role: "user", Content: "Can you forge me a legendary sword?"},
            },
            MaxTokens:   150,
            Temperature: 0.8,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

use async_openai::{
    Client,
    config::OpenAIConfig,
    types::{CreateChatCompletionRequestArgs, ChatCompletionRequestMessage},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = OpenAIConfig::new()
        .with_api_key("mg_live_YOUR_KEY")
        .with_api_base("https://api.monstergaming.ai/v1");
    let client = Client::with_config(config);

    let request = CreateChatCompletionRequestArgs::default()
        .model("deepseek-chat")
        .messages(vec![
            ChatCompletionRequestMessage::System("You are a grumpy dwarf blacksmith.".into()),
            ChatCompletionRequestMessage::User("Can you forge me a legendary sword?".into()),
        ])
        .max_tokens(150_u32)
        .temperature(0.8)
        .build()?;

    let response = client.chat().create(request).await?;
    println!("{}", response.choices[0].message.content.as_deref().unwrap_or(""));
    Ok(())
}

Response

200 OK

{
  "id": "chatcmpl-mg_abc123",
  "object": "chat.completion",
  "created": 1716345600,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "*slams hammer on anvil* A legendary sword, you say? Bah! Do you have any idea what that takes? Three months of labor, dragon-fire tempering, and materials that cost more than your entire village. Come back with 500 gold and a chunk of mithril, then we will talk."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 68,
    "total_tokens": 110
  }
}

Streaming (SSE)

Stream responses in real-time using Server-Sent Events. Set "stream": true in your chat completion request, or use the dedicated streaming endpoint.

POST /v1/stream Auth Required

Dedicated streaming endpoint. Same request body as /v1/chat/completions, always returns SSE.

Code Examples

curl -N -X POST https://api.monstergaming.ai/v1/chat/completions \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Generate a quest description for a haunted castle."}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="mg_live_YOUR_KEY",
    base_url="https://api.monstergaming.ai/v1"
)

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Generate a quest description for a haunted castle."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "mg_live_YOUR_KEY",
  baseURL: "https://api.monstergaming.ai/v1",
});

const stream = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "Generate a quest description for a haunted castle." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

SSE Event Format

data: {"id":"chatcmpl-mg_abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"A haunted"},"index":0}]}

data: {"id":"chatcmpl-mg_abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" castle"},"index":0}]}

data: [DONE]

Safe events only: The gateway filters SSE events to a safe allowlist (message_start, content_block_delta, message_stop, etc.). Internal provider events are never forwarded to clients.

Structured Output

POST /v1/structured Auth Required

Request responses conforming to a JSON schema. Ideal for game data generation — loot tables, quest specs, NPC stats.

Code Example

curl -X POST https://api.monstergaming.ai/v1/structured \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Generate a loot drop for a dragon boss"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "loot_drop",
        "schema": {
          "type": "object",
          "properties": {
            "item_name": {"type": "string"},
            "rarity": {"type": "string", "enum": ["common","uncommon","rare","epic","legendary"]},
            "damage": {"type": "integer"},
            "effects": {"type": "array", "items": {"type": "string"}}
          },
          "required": ["item_name", "rarity", "damage"]
        }
      }
    }
  }'

Monster-GPT

Monster-GPT is an intelligent routing layer. When you set "model": "monster-gpt", the gateway classifies your prompt, selects the optimal game-development discipline specialist, injects domain-specific context, and routes to the best backend model.

Zero configuration: Monster-GPT handles model selection, prompt engineering, and domain expertise automatically. Ask about shaders and it routes to a Technical Artist specialist; ask about netcode and it picks a Network Programmer expert.

Supported Disciplines

Discipline	Specialist	Example Prompts
programming	Technical Director	Architecture, code review, C++/Blueprint
rendering	Rendering Engineer	Ray tracing, Nanite, Lumen, deferred shading
shader	Technical Artist	HLSL, GLSL, material graphs, compute shaders
art	Look Dev	Materials, textures, PBR, lighting
animation	Animator	Blend trees, state machines, IK/FK, retargeting
design	Design Director	Game balance, economy, progression, meta
narrative	Narrative Director	Dialogue, branching stories, quests, lore
multiplayer	Network Engineer	Matchmaking, lobbies, dedicated servers
qa	QA Lead	Test plans, bug triage, coverage analysis
localization	Localization Lead	Translation, cultural adaptation, string tables
audio	Audio Director	Sound design, FMOD, Wwise, spatial audio
vfx	VFX Artist	Niagara, particles, beams, trails

Plus 20+ more disciplines including environment art, character art, sculpting, UI/UX, physics, level design, production, tools, pipeline, and live ops. Tier restrictions apply — Free/PAYG users get general only; Starter and above unlock domain specialists.

Code Example

curl -X POST https://api.monstergaming.ai/v1/chat/completions \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "monster-gpt",
    "messages": [
      {"role": "user", "content": "How do I implement rollback netcode for a fighting game in Unreal Engine 5?"}
    ]
  }'

The response includes a X-Monster-Discipline header indicating which specialist handled the request.

Embeddings

POST /v1/embeddings Auth Required

Generate vector embeddings for text. Useful for semantic search, NPC memory retrieval, and content similarity.

Request Body

Parameter	Type		Description
input	string \| string[]	required	Text to embed. Pass a single string or an array of strings for batch embedding.
model	string	optional	Embedding model. Options: `text-embedding-3-small` (1536d), `text-embedding-3-large` (3072d), `embedding-001` (768d, Google). Default: `text-embedding-3-small`.
encoding_format	string	optional	`float` (default) or `base64`.
dimensions	integer	optional	Truncate output to this many dimensions (supported by text-embedding-3 models).

Code Example

curl -X POST https://api.monstergaming.ai/v1/embeddings \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "The blacksmith forged a legendary sword of fire.",
    "model": "text-embedding-3-small"
  }'

Models

GET /v1/models Auth Required

List all models available for your tier. Returns an OpenAI-compatible model list.

GET /v1/models/health Public

Per-model availability and success rates over the last 24 hours.

GET /v1/models/catalog Public

Complete model catalog with list pricing, provider, and tier minimum. No auth required. Cached for 1 hour at the CDN edge.

Response

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-chat",
      "shorthand": "deepseek-chat",
      "object": "model",
      "owned_by": "deepseek",
      "tier_minimum": "free",
      "pricing": {
        "input_per_1m": 0.14,
        "output_per_1m": 0.28,
        "currency": "usd"
      }
    }
  ],
  "_meta": {
    "total": 181,
    "providers": ["deepseek", "google", "anthropic", "openai", ...],
    "tiers": [
      { "name": "Free", "price_monthly_usd": 0, "models_available": 12 },
      { "name": "Pay-As-You-Go", "price_monthly_usd": 0, "models_available": 30 },
      ...
    ]
  }
}

Popular Models

Model	Provider	Min. Tier	Best For
deepseek-chat	DeepSeek	Free	General purpose, cost-effective
gemini-3-flash	Google	Free	Fast responses, multimodal
monster-gpt	Monster Gaming	Free	Auto-routed game dev expert
claude-sonnet-4-6	Anthropic	Starter	Code generation, reasoning
gpt-4o	OpenAI	Starter	Versatile, multimodal
claude-opus-4-6	Anthropic	Pro	Complex architecture, deep reasoning

Threads

Threads provide persistent conversation memory for NPCs. Each thread tracks a conversation between a player and an NPC, persisting across sessions and model switches.

POST /v1/threads Auth Required

Create a new conversation thread for an NPC.

Request Body

Parameter	Type		Description
npc_id	string	optional	Unique NPC identifier within your game.
system_prompt	string	optional	System prompt defining the NPC personality and behavior.
metadata	object	optional	Arbitrary key-value metadata (e.g. location, faction, quest state).

GET /v1/threads Auth Required

List threads. Filter by npc_id, paginate with limit and before.

GET /v1/threads/{thread_id} Auth Required

Get a specific thread with metadata and message count.

GET /v1/threads/{thread_id}/messages Auth Required

Retrieve conversation history for a thread. Use limit to control page size.

PATCH /v1/threads/{thread_id} Auth Required

Update thread metadata, system prompt, or NPC ID without losing conversation history.

DELETE /v1/threads/{thread_id} Auth Required

Delete a thread and all its messages.

Batch NPC Population

POST /v1/threads/batch Auth Required

Create up to 50 NPC threads in a single call. Ideal for populating a game world at startup.

curl -X POST https://api.monstergaming.ai/v1/threads/batch \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "npcs": [
      {
        "npc_id": "blacksmith_01",
        "npc_template": "merchant",
        "system_prompt": "You are a grumpy dwarf who specializes in legendary weapons.",
        "metadata": {"location": "Iron Forge", "faction": "dwarves"}
      },
      {
        "npc_id": "innkeeper_01",
        "system_prompt": "You are a cheerful innkeeper who loves gossip and rumor.",
        "metadata": {"location": "The Rusty Mug"}
      }
    ]
  }'

Thread Export

POST /v1/threads/export Auth Required

Export conversation data in JSONL (OpenAI fine-tuning format) or JSON. Use for training custom models on your NPC dialogue.

Thread State

Attach arbitrary game state to a thread. The NPC system prompt can reference this state for context-aware responses (e.g., quest progress, inventory, player reputation).

POST /v1/threads/{thread_id}/state Auth Required

Update game state on a thread. Fires a thread.state_changed webhook.

GET /v1/threads/{thread_id}/state Auth Required

Retrieve current game state for a thread.

curl -X POST https://api.monstergaming.ai/v1/threads/thr_abc123/state \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quest_progress": "talked_to_guard",
    "player_reputation": 75,
    "inventory": ["health_potion", "iron_sword"],
    "time_of_day": "night"
  }'

NPC Actions

Register game actions an NPC can trigger (open shop, give quest, attack). The AI will emit structured action calls alongside dialogue.

PUT /v1/threads/{thread_id}/actions Auth Required

GET /v1/threads/{thread_id}/actions Auth Required

Retrieve the current action schema.

curl -X PUT https://api.monstergaming.ai/v1/threads/thr_abc123/actions \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "name": "offer_trade",
        "description": "Present an item for sale with a price",
        "parameters": {
          "item_id": {"type": "string"},
          "price": {"type": "integer"},
          "currency": {"type": "string"}
        }
      },
      {
        "name": "give_quest",
        "description": "Offer the player a quest",
        "parameters": {
          "quest_id": {"type": "string"},
          "difficulty": {"type": "string", "enum": ["easy","medium","hard"]}
        }
      }
    ]
  }'

NPC Templates

Pre-built personality archetypes for common NPC roles. Skip prompt engineering — templates include system prompts, suggested actions, and response style tuning.

GET /v1/npc/templates Public

List available NPC templates. Filter by tags query parameter.

GET /v1/npc/templates/{template_id} Public

Get full template details including system prompt, actions, and example usage.

Available Templates

ID	Name	Tags
merchant	Merchant	economy, rpg, shop, trade
quest_giver	Quest Giver	rpg, quest, npc
guard	Guard	security, patrol, rpg
villain	Villain	antagonist, boss, dramatic
healer	Healer	rpg, support, temple
companion	Companion	party, rpg, loyal

Group Threads

Multi-NPC conversation scenes. Create a shared thread with 2–20 NPCs and direct individual NPCs to speak.

POST /v1/threads/group Auth Required

Create a group conversation thread with multiple NPCs.

POST /v1/threads/{thread_id}/speak Auth Required

Direct a specific NPC in the group to respond. Pass npc_id and messages in the body.

Debug Symbols

Upload, manage, and look up debug symbol files (.sym, .pdb, .dSYM) for crash symbolication. Symbol files are stored in R2 with content validation and path traversal prevention.

POST /v1/debug/symbols/upload

Upload a debug symbol file (max 10MB direct). Requires multipart/form-data with file, module_name, debug_id, platform, file_type. Content validated against magic bytes.

POST /v1/debug/symbols/presign

Request a presigned upload URL for large files (up to 500MB). Returns a one-time upload_token valid for 1 hour.

PUT /v1/debug/symbols/upload/:token

Complete a presigned upload. No API key required — the token IS the auth. Send the raw file as application/octet-stream.

GET /v1/debug/symbols/lookup

Look up symbols by module_name and debug_id. Case-insensitive for Windows Symbol Server (symsrv.dll) compatibility.

Debug Sessions

Create and manage debug sessions for DAP (Debug Adapter Protocol) integration. Sessions are soft-deleted (archived) to preserve audit trail.

POST /v1/debug/sessions

Create a new debug session. Body must be under 512KB. Fields: name (required), platform, engine, metadata.

GET /v1/debug/sessions

List all active (non-archived) debug sessions for the authenticated developer.

Crash Reports

Ingest crash data with optional minidump files, track crash trends, and manage crash status. Minidumps are validated for MDMP magic bytes, PII-sanitized, and content-hash deduplicated.

POST /v1/debug/crashes

Submit a crash report with optional minidump. Auto-generates a fingerprint from the top-3 stack frames (SHA-256). Returns 503 if R2 is unavailable but the crash metadata is still stored in D1.

GET /v1/debug/crashes

List crash reports. Filter by game_id, status. Limit up to 100 per page.

GET /v1/debug/crashes/trends

Crash trends grouped by fingerprint: occurrence count, first/last seen, regression detection, platform/version aggregation. Filter by game_id, since, until.

GET /v1/debug/crashes/stats

Aggregate crash statistics: total crashes, unique fingerprints, status breakdown, 24h/7d velocity, platform/game counts, dedup savings.

PATCH /v1/debug/crashes/:id

Update crash status. Valid values: new, investigating, resolved, wont_fix.

Crash Analysis

AI-powered crash analysis using DeepSeek Chat. Analyzes stored crashes by ID or inline stack traces. Provides root cause, severity, fix suggestion, prevention, and related patterns.

POST /v1/debug/analyze

Analyze a crash. Provide crash_id for stored crashes or stack_trace for inline analysis. Optional question field (max 500 chars) for specific developer questions. Auto-updates crash status to investigating on success.

Example Request

curl -X POST https://api.monstergaming.ai/v1/debug/analyze \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "stack_trace": ["GameEngine::Update", "Physics::Step", "CollisionCheck::SIGSEGV"],
    "platform": "windows",
    "engine": "unreal",
    "question": "Why does this crash only on level 3?"
  }'

Example Response

{
  "crash_id": null,
  "analysis": "**Root Cause:** Null pointer dereference in CollisionCheck...",
  "model": "deepseek-chat",
  "analyzed_at": "2026-05-23T10:00:00.000Z"
}

Webhook Management

Register HTTPS endpoints to receive real-time notifications about thread events. All payloads are signed with HMAC-SHA256 for verification.

POST /v1/webhooks Auth Required

Request Body

Parameter	Type		Description
url	string	required	HTTPS endpoint URL to receive webhook payloads.
events	string[]	required	Array of event types to subscribe to.

GET /v1/webhooks Auth Required

List all registered webhooks.

DELETE /v1/webhooks/{webhook_id} Auth Required

Delete a webhook.

POST /v1/webhooks/{webhook_id}/ping Auth Required

Send a test ping to verify your endpoint connectivity.

Webhook Event Types

Event	Description
thread.created	A new thread was created.
thread.message	A new message was added to a thread.
thread.action	An NPC triggered a game action (offer_trade, give_quest, etc.).
thread.state_changed	Game state on a thread was updated.
npc.first_interaction	A player interacted with an NPC for the first time.
player.credit_low	The developer's credit balance is running low.

Payload Format

{
  "event": "thread.message",
  "timestamp": "2026-05-22T12:00:00.000Z",
  "data": {
    "thread_id": "thr_abc123",
    "message_id": "msg_def456",
    "role": "assistant",
    "content": "The blacksmith nods slowly...",
    "npc_id": "blacksmith_01"
  }
}

Signature verification: Each webhook delivery includes a X-Webhook-Signature header containing an HMAC-SHA256 digest of the payload using your webhook secret (whsec_...). Always verify signatures before processing.

Delivery Logs

GET /v1/webhooks/deliveries Auth Required

View recent webhook delivery attempts. Filter by status (delivered or failed). Paginate with limit (max 200).

Billing & Credits

GET /v1/credits/balance Auth Required

Real-time credit balance, daily usage, and expiration dates.

GET /v1/billing/manage Auth Required

Get a Stripe checkout or customer portal URL. Optionally pass ?tier=pro to target a specific upgrade tier.

GET /v1/billing/spend-limit Auth Required

View your current monthly and daily spend caps.

PUT /v1/billing/spend-limit Auth Required

Set or update your monthly/daily spend cap. Set to null to remove.

curl -X PUT https://api.monstergaming.ai/v1/billing/spend-limit \
  -H "Authorization: Bearer mg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthly_cap_usd": 100, "daily_cap_usd": 10}'

Usage

GET /v1/usage Auth Required

Detailed usage breakdown with daily aggregates, per-model cost, projections, and credit forecast. Pass ?days=30 for the lookback window (max 90). Supports ?format=csv for spreadsheet export.

GET /v1/logs Auth Required

Per-request audit log with model, tokens, cost, and latency. Paginate with limit (max 200) and before cursor.

Telemetry

The telemetry API lets SDK extensions and tools report usage events for analytics dashboards.

POST /v1/telemetry/event Auth Required

Record a telemetry event. Used by the VS Code extension and CLI tools.

Valid Events

generate_started, generate_completed, generate_failed, error_fix_started, error_fix_applied, session_start, session_end, first_call, upgrade_shown, upgrade_clicked, and more.

Valid Sources

vscode_extension, web_portal, cli, api

GET /v1/telemetry/summary Auth Required

Get aggregated telemetry summary for your account.

Key Management

GET /v1/whoami Auth Required

Lightweight key validation. Returns tier, environment, game ID, and rate limits without consuming a rate limit token.

GET /v1/keys/me Auth Required

Full key introspection: tier, credit balance, available models, NPC rate limits, data region, allowed/blocked providers.

GET /v1/keys/health Auth Required

Key rotation health check. Reports key age, last-used date, and rotation recommendations.

Key Rotation Policy

Age	Status	Recommendation
< 90 days	Healthy	No action needed
90–180 days	Aging	Consider rotating
> 180 days	Stale	Rotate immediately

Official SDKs

Monster Gaming publishes official SDKs on all major package registries. Since the API is OpenAI-compatible, you can also use any OpenAI SDK by changing the base URL.

Language	Package	Install
Python	monstergaming	`pip install monstergaming`
Node.js	@monstergaming/sdk	`npm install @monstergaming/sdk`
Rust	monstergaming	`cargo add monstergaming`
Go	monstergaming-go	`go get github.com/Monster-Gaming-ai/sdk-go`
C#	MonsterGaming.SDK	`dotnet add package MonsterGaming.SDK`
Java	com.monstergaming:sdk	Maven Central (groupId: `com.monstergaming`)
C++	monstergaming-cpp	Header-only. Clone from GitHub.

One-Line Install

curl -fsSL https://monstergaming.ai/install.sh | sh

Detects your environment and installs both Python and Node.js SDKs automatically.

OpenAI SDK Compatibility

The Monster Gaming API is a drop-in replacement for the OpenAI API. Just change the base URL and API key:

from openai import OpenAI

# Just change these two lines — everything else works as-is
client = OpenAI(
    api_key="mg_live_YOUR_KEY",
    base_url="https://api.monstergaming.ai/v1"
)

# All OpenAI SDK methods work: chat, streaming, embeddings, etc.
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello from Monster Gaming!"}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

// Just change these two lines
const client = new OpenAI({
  apiKey: "mg_live_YOUR_KEY",
  baseURL: "https://api.monstergaming.ai/v1",
});

// Everything else works as-is
const response = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "Hello from Monster Gaming!" }],
});
console.log(response.choices[0].message.content);

# Set environment variables — many tools/libraries honor these
export OPENAI_API_KEY="mg_live_YOUR_KEY"
export OPENAI_BASE_URL="https://api.monstergaming.ai/v1"

# Now any tool that uses the OpenAI API will route through Monster Gaming
# Examples: LangChain, LlamaIndex, AutoGen, CrewAI, etc.

Pricing Tiers

Tier	Monthly	Discount	Rate Limit	Models	Seats
Free	$0	0%	10 rpm	Budget (deepseek-chat, gemini-flash, monster-gpt, etc.)	1
Pay-as-you-go	$0.99	0%	30 rpm	Budget models	2
Starter	$39.99	12%	60 rpm	Standard (+ Claude Sonnet, GPT-4o, Gemini Pro, etc.)	5
Pro	$99.99	22%	300 rpm	Premium (+ Claude Opus, o3, GPT-5.4)	10
Studio	$249.99	35%	1,000 rpm	All models + dedicated support	25
Enterprise	Custom	Custom	Custom	All models + custom SLA + SSO + data residency	Unlimited

Programmatic pricing: Use GET /v1/pricing for machine-readable per-model list prices, GET /v1/tiers for tier details, and GET /v1/cost-calculator for cost estimates.

Error Codes

HTTP	Code	Retryable	Description
400	INVALID_REQUEST	No	Malformed request body, missing required fields.
400	INVALID_ROLE	No	Message role not in allowed set (system, user, assistant, tool).
400	INVALID_MAX_TOKENS	No	max_tokens out of range (1–128,000).
400	MODEL_NOT_FOUND	No	Requested model does not exist. Use `GET /v1/models` for the full list.
400	CONTEXT_OVERFLOW	No	Prompt exceeds model context window. Trim history or switch to a larger model.
401	INVALID_API_KEY	No	Missing or invalid API key. Get a key at monstergaming.ai/signup.
402	CREDITS_EXHAUSTED	No	Credit balance depleted. Add credits or upgrade tier.
403	TOS_REQUIRED	No	Terms of Service not yet accepted.
403	TIER_RESTRICTED	No	Model requires a higher tier. Upgrade or use a free-tier model.
413	PAYLOAD_TOO_LARGE	No	Request body exceeds 64KB (completions) or 512KB (embeddings).
429	RATE_LIMITED	Yes	Rate limit exceeded. Retry after `Retry-After` seconds.
429	SPEND_CAP_EXCEEDED	Yes	Daily spend cap reached. Resets at midnight UTC.
429	MONTHLY_CAP_EXCEEDED	Yes	Monthly spend cap reached. Increase cap or wait for next billing cycle.
503	PROVIDER_UNAVAILABLE	Yes	LLM provider temporarily down. Retry, or set `allow_fallback: true`.
503	MAINTENANCE	Yes	Platform under scheduled maintenance. Check `/status` for ETA.

Automatic retry: Every error response includes is_retryable and (when applicable) retry_after and reset_at fields. SDKs handle retryable errors automatically with exponential backoff.

System Status

GET /status Public

HTML status page with real-time provider health, circuit breaker states, and model counts. Auto-refreshes every 30 seconds.

GET /v1/status Public

JSON status API for monitoring integrations (Betteruptime, Pingdom, etc.).

GET /v1/health Public

JSON health check with subsystem status (KV, D1, config), version, and uptime. Returns 200 (healthy/degraded) or 503 (unhealthy).

GET /v1/slo Public

Service Level Objectives: availability targets, latency percentiles, error rate commitments.

Changelog

GET /v1/changelog Public

Machine-readable changelog of API changes, new features, and deprecations.

GET /v1/version Public

Current API version identifier.

For the full human-readable changelog, visit monstergaming.ai/changelog.