API Reference

GameDesignerX API & MCP

Access your GDD data — objects, objectives, achievements, localization, economy, and build log — from your game engine, pipeline scripts, or custom tools via the REST API, or connect AI assistants like Claude and Cursor directly with the MCP Connector.

v1 · StablePro or Team PlanLooking for module guides? →

Overview

The GameDesignerX API lets you integrate your live GDD data with external systems. Use it to power in-engine tooling, CI/CD pipelines, content export scripts, or custom dashboards. Most resources are read-only; the Build Log resource additionally supports write access so you can post entries directly from your CI/CD pipeline or build scripts.

Access is scoped per project using an API key. Each key is tied to one project and one user account. Keys can be created and revoked at any time from the project dashboard without affecting other keys.

Paid plan required. The API is available on Pro and Team. Pro keys are rate-limited to 120 requests/min; Team keys to 600 requests/min. Requests authenticated with a key belonging to a Free account receive a 403 Forbidden response.

Authentication

Every request must include a valid API key. Pass it using either of these headers:

Header	Example	Notes
`x-api-key`	`gdx_a1b2c3d4...`	Preferred. Short and explicit.
`Authorization`	`Bearer gdx_a1b2c3d4...`	Standard Bearer token format.

API keys have the prefix gdx_ followed by 32 hex characters. They are shown in full only once at creation — store them securely and treat them like passwords.

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/YOUR_PROJECT_ID/objects \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Never expose API keys in client-side code or public repositories. If a key is compromised, revoke it immediately from the dashboard and issue a new one.

Base URL

All API endpoints are relative to the following base URL:

https://gamedesignerx.com/api/v1

All responses are JSON. Successful responses always include the resource key at the top level of the response object. There is no pagination — the full collection is returned.

Errors

The API uses standard HTTP status codes. Error responses have the following shape:

JSON

{
  "error": "This API key is not authorized for this project."
}

Status	Meaning
`200 OK`	Request succeeded. Data is in the response body.
`400 Bad Request`	Missing or malformed request parameters.
`401 Unauthorized`	API key is missing, malformed, or has been revoked.
`403 Forbidden`	Key is valid but not authorized for this project, or the plan is too low (API requires Pro or Team).
`404 Not Found`	The requested resource type does not exist.
`429 Too Many Requests`	Per-key rate limit exceeded — see Rate Limits for per-plan budgets.
`502 Bad Gateway`	Internal error communicating with the GDD server. Retry after a moment.

Rate Limits

Each API key is rate-limited per minute by the plan of the key's owner. Exceeding the limit returns 429 Too Many Requests; wait a minute and retry.

Plan	Limit	Notes
Pro	120 requests / minute	Comfortable for engine plugins, CI/CD, daily exports.
Team	600 requests / minute	5× Pro — built for BI pipelines and large-team integrations.

The API is designed for tooling and pipeline use, not real-time game queries. Cache responses locally in your engine or build process rather than making per-frame requests.

Resources

All resource endpoints follow the same pattern:

GET /projects/{projectId}/objects
GET /projects/{projectId}/objectives
GET /projects/{projectId}/achievements
GET /projects/{projectId}/localization
GET /projects/{projectId}/economy
GET /projects/{projectId}/buildlog
POST /projects/{projectId}/buildlog

The projectId is the unique ID of the project, visible in the URL when you open a project in the dashboard (e.g. gamedesignerx.com/project/64f3a...).

Objects

Returns every game object (item) defined in the project — weapons, armor, consumables, quest items, props, and any custom categories your team has created.

GET/projects/{projectId}/objects

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/objects \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

JavaScript (fetch)

const res = await fetch(
  "https://gamedesignerx.com/api/v1/projects/64f3abc123/objects",
  { headers: { "x-api-key": "gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" } }
);
const { objects } = await res.json();

Response

JSON

{
  "objects": [
    {
      "_id": "64f3abc123456789",
      "objectid": "550e8400-e29b-41d4-a716-446655440000",
      "objectname": "Iron Sword",
      "objectrawname": "IRON_SWORD",
      "objectcategory": "Weapon",
      "objecttype": "Melee Weapon",
      "objectrarity": "Common",
      "objectdescription": "A sturdy blade forged from refined iron ore.",
      "objectlore": "Standard-issue sword of the City Guard since 3rd Age.",
      "objectorigin": "Blacksmith — Iron District",
      "objectusage": "Main-hand melee attack",
      "objtags": ["Physical", "Tradeable", "Upgradeable"],
      "objectimage": "https://cdn.example.com/items/iron_sword.png",
      "objectproperties": [
        {
          "id": "prop_001",
          "attributename": "Attack Damage",
          "attributetype": "Stat",
          "attributedescription": "10"
        },
        {
          "id": "prop_002",
          "attributename": "Attack Speed",
          "attributetype": "Stat",
          "attributedescription": "1.2"
        }
      ]
    }
  ]
}

Field	Type	Description
`objectid`	string	UUID assigned at creation.
`objectname`	string	Display name of the object.
`objectrawname`	string	Internal/code name (e.g. IRON_SWORD).
`objectcategory`	string	Category: Weapon, Armor, Consumable, etc.
`objecttype`	string	Sub-type within the category.
`objectrarity`	string	Common, Uncommon, Rare, Epic, Legendary, …
`objectdescription`	string	Player-facing description text.
`objectlore`	string	In-universe lore or flavour text.
`objectorigin`	string	Where the object comes from.
`objectusage`	string	How the object is used in-game.
`objtags`	string[]	Tags: Physical, Magical, Stackable, etc.
`objectimage`	string	URL to the object thumbnail image.
`objectproperties`	Property[]	Custom stat/ability/effect entries.

Property object

Field	Type	Description
`id`	string	Unique ID for this property row.
`attributename`	string	Property name (e.g. Attack Damage).
`attributetype`	string	Stat, Ability, Effect, Requirement, etc.
`attributedescription`	string	Value or description of the property.

Objectives

Returns the full list of objectives defined in the project. Objectives can be nested — a sub-objective references its parent via parentid.

GET/projects/{projectId}/objectives

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/objectives \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Response

JSON

{
  "objectives": [
    {
      "_id": "64f3abc123456789",
      "objectiveid": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Reach the Citadel",
      "description": "Travel through the three districts and reach the Citadel gates.",
      "type": "Main",
      "parentid": null
    },
    {
      "_id": "64f3abc123456790",
      "objectiveid": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Find the Hidden Pass",
      "description": "Discover the shortcut through the old sewers.",
      "type": "Optional",
      "parentid": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

Field	Type	Description
`objectiveid`	string	UUID assigned at creation.
`name`	string	Objective title shown to the player.
`description`	string	Detailed objective description.
`type`	string	Main, Optional, Hidden, Collectible, etc.
`parentid`	string \| null	objectiveid of the parent; null for top-level objectives.

Achievements

Returns the project achievement list. The shape of each achievement entry is defined by your team in the GDD editor — the API returns the array as-is.

GET/projects/{projectId}/achievements

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/achievements \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Response

JSON

{
  "achievements": [
    {
      "id": "ach_001",
      "name": "First Blood",
      "description": "Defeat your first enemy.",
      "icon": "https://cdn.example.com/achievements/first_blood.png",
      "condition": "Kill 1 enemy",
      "points": 10,
      "secret": false
    },
    {
      "id": "ach_002",
      "name": "Legendary Collector",
      "description": "Collect 10 legendary items.",
      "icon": "https://cdn.example.com/achievements/collector.png",
      "condition": "Own 10 items with rarity Legendary",
      "points": 50,
      "secret": false
    }
  ]
}

Achievement fields are fully customizable in the GDD editor. The structure shown above reflects a typical setup; your project may use different field names or additional fields. The API returns the raw stored data without transformation.

Localization

Returns the complete localization table for the project, including all configured languages and every string key with its translations.

GET/projects/{projectId}/localization

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/localization \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Response

JSON

{
  "localization": [
    {
      "key": "ITEM_IRON_SWORD_NAME",
      "en": "Iron Sword",
      "de": "Eisenschwert",
      "fr": "Épée en Fer",
      "ja": "鉄の剣"
    },
    {
      "key": "ITEM_IRON_SWORD_DESC",
      "en": "A sturdy blade forged from refined iron ore.",
      "de": "Eine robuste Klinge aus gereinigtem Eisenerz.",
      "fr": "Une lame robuste forgée à partir de minerai de fer raffiné.",
      "ja": "精錬された鉄鉱石から鍛えられた頑丈な刃。"
    },
    {
      "key": "OBJ_REACH_CITADEL",
      "en": "Reach the Citadel",
      "de": "Erreiche die Zitadelle",
      "fr": "Atteindre la Citadelle",
      "ja": "城塞に到達する"
    }
  ],
  "languages": ["en", "de", "fr", "ja"]
}

Field	Type	Description
`localization`	LocaleEntry[]	Array of string entries, one per localization key.
`languages`	string[]	Language codes configured in the project (e.g. en, de, fr).
`localization[].key`	string	Unique string identifier (e.g. ITEM_IRON_SWORD_NAME).
`localization[].{lang}`	string	Translation value for each configured language code.

Use the key field as the lookup identifier in your game engine. Pull the appropriate language column at runtime based on the player's locale setting.

Economy

Returns the economy sheet — every tracked item with its buy / sell prices, drop rate, XP reward, rarity, and category. Useful for keeping in-game shop prices, loot tables, or balancing spreadsheets in sync with the canonical GDD numbers.

GET/projects/{projectId}/economy

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/economy \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Response

JSON

{
  "economy": [
    {
      "id":         "row_iron_sword",
      "name":       "Iron Sword",
      "category":   "Weapons",
      "rarity":     "Common",
      "buy_price":  120,
      "sell_price": 48,
      "drop_rate":  0.18,
      "xp_reward":  0,
      "notes":      "Baseline starter weapon — used as a comparison anchor."
    },
    {
      "id":         "row_health_potion_l",
      "name":       "Large Health Potion",
      "category":   "Consumables",
      "rarity":     "Uncommon",
      "buy_price":  85,
      "sell_price": 25,
      "drop_rate":  0.06,
      "xp_reward":  0,
      "notes":      "Restores 60% HP. Cap 5 in inventory."
    }
  ]
}

Field	Type	Description
`economy`	EconomyRow[]	Array of economy entries, one per tracked item or resource.
`economy[].id`	string	Stable per-row identifier.
`economy[].name`	string	Display name of the item / resource.
`economy[].category`	string	Free-form bucket (e.g. Weapons, Consumables, Materials).
`economy[].rarity`	string	Rarity tier (e.g. Common, Rare, Legendary).
`economy[].buy_price`	number	Buy price in your in-game currency. 0 if not for sale.
`economy[].sell_price`	number	Sell-back / vendor price. 0 if non-sellable.
`economy[].drop_rate`	number	Drop probability (0-1). 0 if not dropped by enemies.
`economy[].xp_reward`	number	XP granted on pickup / use, if any.
`economy[].notes`	string	Designer notes — balancing context, intended usage, etc.

Pair this with the localization endpoint to render the same item names in any supported language without round-tripping back to the GDD.

Build Log

The Build Log tracks versioned build entries for the project — release notes, patch notes, or any milestone your team wants recorded. Unlike the other resources, this endpoint supports both reading and writing, so you can post entries directly from your CI/CD pipeline or build scripts.

List entries

GET/projects/{projectId}/buildlog

Shell (curl)

curl https://gamedesignerx.com/api/v1/projects/64f3abc123/buildlog \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

JSON

{
  "buildlog": [
    {
      "entryid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "version": "1.2.0",
      "title": "Combat overhaul",
      "body": "Reworked hitbox detection. Added combo system. Fixed parry timing window.",
      "status": "released",
      "platform": "PC",
      "tags": ["combat", "fix"],
      "source": "api",
      "releasedAt": "2026-05-21T14:30:00.000Z",
      "createdAt": "2026-05-21T14:30:00.000Z"
    }
  ]
}

Create an entry

POST/projects/{projectId}/buildlog

Post a JSON body with the entry fields. version and body are required; everything else is optional.

Shell (curl)

curl -X POST https://gamedesignerx.com/api/v1/projects/64f3abc123/buildlog \
  -H "x-api-key: gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.2.1",
    "title": "Hotfix — save corruption",
    "body": "Fixed a bug where saving during a cutscene could corrupt the save file.",
    "status": "released",
    "platform": "All",
    "tags": ["hotfix", "save"]
  }'

JavaScript (fetch)

const res = await fetch(
  "https://gamedesignerx.com/api/v1/projects/64f3abc123/buildlog",
  {
    method: "POST",
    headers: {
      "x-api-key": "gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      version: "1.2.1",
      title:   "Hotfix — save corruption",
      body:    "Fixed a bug where saving during a cutscene could corrupt the save file.",
      status:  "released",
      tags:    ["hotfix", "save"],
    }),
  }
);
const { entry } = await res.json(); // 201 Created

JSON

{
  "status": true,
  "entry": {
    "entryid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "version": "1.2.1",
    "title": "Hotfix — save corruption",
    "body": "Fixed a bug where saving during a cutscene could corrupt the save file.",
    "status": "released",
    "platform": "",
    "tags": ["hotfix", "save"],
    "source": "api",
    "releasedAt": "2026-05-21T15:00:00.000Z",
    "createdAt": "2026-05-21T15:00:00.000Z"
  }
}

Request body fields

Field	Type	Required	Description
`version`	string	Yes	Build or release version string (e.g. "1.2.1", "0.9.0-beta").
`body`	string	Yes	Release notes or changelog text for this entry.
`title`	string	No	Optional short title (e.g. "Combat overhaul").
`status`	string	No	"released" (default) or "draft". Draft entries are visible in the dashboard but not shown on the public changelog.
`platform`	string	No	Target platform (e.g. "PC", "All", "Steam").
`tags`	string[]	No	Freeform tags (e.g. ["hotfix", "balance"]).

Response fields

Field	Type	Description
`entryid`	string	UUID assigned to this entry.
`version`	string	The version string provided in the request.
`title`	string	Entry title, empty string if not provided.
`body`	string	Release notes text.
`status`	string	"released" or "draft".
`platform`	string	Platform string, empty if not provided.
`tags`	string[]	Array of tags.
`source`	string	"api" when created via this endpoint, "dashboard" when created in the editor.
`releasedAt`	string \| null	ISO timestamp of release. Null for drafts.
`createdAt`	string	ISO timestamp of when the entry was created.

Automate build log entries in your CI pipeline: call the POST endpoint after every successful build and pass your semantic version, commit message summary, or changelog fragment as body. Entries posted via the API are tagged with source: "api" so they're easy to distinguish in the dashboard.

MCP (AI Assistants)

Connect AI assistants like Claude and Cursor directly to a project over the Model Context Protocol (MCP). The server speaks streamable HTTP — no local bridge or download required.

Each connection is scoped to one project and authenticates with an MCP token (a gdx_ key). MCP is available on Pro and Team, and tool access respects your role on the project.

Endpoint

Each project has its own MCP endpoint. Create a connection token under Dashboard → MCP.

POST/api/mcp/{projectId}

https://gamedesignerx.com/api/mcp/YOUR_PROJECT_ID

Authentication

Send your MCP token as a Bearer header. The token is shown in full only once, when you create the connection.

HTTP

Authorization: Bearer gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Client setup

Add the connection to your MCP client config. The dashboard generates this snippet with your token already filled in.

Cursor — ~/.cursor/mcp.json

JSON

{
  "mcpServers": {
    "gamedesignerx": {
      "url": "https://gamedesignerx.com/api/mcp/YOUR_PROJECT_ID",
      "headers": {
        "Authorization": "Bearer gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
      }
    }
  }
}

Claude Desktop — Settings → Connectors → Add custom

JSON

{
  "mcpServers": {
    "gamedesignerx": {
      "url": "https://gamedesignerx.com/api/mcp/YOUR_PROJECT_ID",
      "headers": {
        "Authorization": "Bearer gdx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
      }
    }
  }
}

Tools & resources

Tools read and write the GDD: characters, objects, objectives, levels, mechanics, locations, lore, ideas, issues, decisions, notes, milestones, build logs, risks, builds and playtests, plus project basics, economy, balance, achievements and localization. Read-only resources (gdx://project/…) are exposed for context loading.

Tools respect your project role. A viewer connection can read but not modify — create, update and delete tools return a read-only error.

API Key Management

API keys are managed entirely through the GameDesignerX dashboard — there are no public API endpoints for creating or revoking keys. This is intentional: key management requires an authenticated session, not an API key.

Creating a key

Open your project and go to Settings → API Keys.
Click New API Key and give it a descriptive name (e.g. "Unreal Plugin — Dev").
Copy the key immediately — it is shown in full only once.
Store it in a secure location such as an environment variable or secrets manager.

Revoking a key

Navigate to Settings → API Keys and click the delete icon next to the key. Revocation takes effect immediately — any subsequent requests with the revoked key return 401 Unauthorized.

Each API key is scoped to a single project. If you need access to multiple projects, create a separate key per project. Keys are also tied to the creating user's plan — if the account is downgraded to Free, all keys on that account stop working. A downgrade from Team to Pro reduces the per-key rate limit from 600 to 120 requests/min.

Open Dashboard

Changelog

May 2026

v1.3 — API opened to Pro

Pro plan now includes API access at 120 requests/min.
Team rate limit raised to 600 requests/min (5×) for heavy integrations.
Per-tier rate limits enforced on each key — exceeding returns 429.

May 2026

v1.2 — Economy resource

New economy resource: list every economy-sheet row via the API.
GET /projects/{projectId}/economy — items, prices, drop rates, XP rewards.
Response shape flattened to a simple { economy: EconomyRow[] } array.

May 2026

v1.1 — Build Log write access

New buildlog resource: list and create build log entries via the API.
POST /projects/{projectId}/buildlog — post entries from CI/CD pipelines.
Entries include version, title, body, status, platform, tags, and source tracking.

May 2025

v1 — Initial release

Public read-only API for objects, objectives, achievements, and localization.
API key authentication with SHA-256 hashed storage.
Team plan gating enforced per request.
Project-scoped keys — one key per project.