API Documentation — ForjeGames

API Referencev1

Getting Started

The ForjeGames API lets you build AI-powered Roblox experiences — convert voice commands to game scripts, transform images into playable maps, and search the Roblox marketplace programmatically. All endpoints are REST-based and return JSON.

Base URL

json

https://api.forjegames.com

1. Get an API key

Sign in to your dashboard and navigate to Settings → API Keys to create a key. The raw key is shown once — save it immediately.

2. Make your first request

bash

curl -X GET https://api.forjegames.com/api/marketplace/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -G --data-urlencode "q=sword"

Authentication

All API requests must be authenticated with a Bearer token in the Authorization header. API keys are prefixed with fg_sk_.

Request Header

bash

Authorization: Bearer fg_sk_your_api_key_here

Security: Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests only.

Endpoints

All endpoints accept and return application/json.

POST/api/ai/voice-to-game

Convert a voice recording or transcript into a Roblox Luau game script. The AI interprets natural language commands and generates structured game logic, event handlers, and UI elements.

Parameters

Parameter	Type	Required	Description
`audio_url`	`string`	Optional	Publicly accessible URL of an audio file (mp3, wav, ogg, webm). Provide either this or transcript.
`transcript`	`string`	Optional	Pre-transcribed text to convert. Used when audio_url is not provided.
`language`	`string`	Optional	BCP-47 language code for transcription. Defaults to "en-US".
`style`	`string`	Optional	Output style hint: "simulator" \| "obby" \| "roleplay" \| "generic". Helps the model target the correct game genre.
`include_ui`	`boolean`	Optional	When true, the response includes ScreenGui XML alongside the Luau script.

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/voice-to-game \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/recording.mp3",
    "style": "simulator",
    "include_ui": true
  }'

Example Response

json

{
  "id": "vtg_a1b2c3d4",
  "status": "complete",
  "transcript": "Create a shop button that opens a store menu with three items",
  "output": {
    "script": "local Players = game:GetService(\"Players\")\n-- generated Luau...",
    "ui_xml": "<ScreenGui>...</ScreenGui>",
    "tokens_used": 1840
  },
  "created_at": "2026-03-28T12:00:00Z"
}

POST/api/ai/image-to-map

Transform an image — concept art, a hand-drawn sketch, or a top-down photo — into a Roblox map definition. Returns a structured JSON blueprint that can be imported via the ForjeGames Studio plugin.

Parameters

Parameter	Type	Required	Description
`image_url`	`string`	Required	Publicly accessible URL of the source image (jpg, png, webp). Max 10 MB.
`map_size`	`number`	Optional	Target map width in studs. Accepted values: 512, 1024, 2048, 4096. Defaults to 1024.
`terrain_type`	`string`	Optional	Dominant terrain material: "grass" \| "sand" \| "snow" \| "rock" \| "mud". Defaults to "grass".
`include_assets`	`boolean`	Optional	When true, the response embeds marketplace asset IDs for auto-placement.
`style`	`string`	Optional	Visual style hint: "realistic" \| "cartoon" \| "lowpoly".

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/image-to-map \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.example.com/concept-art.png",
    "map_size": 2048,
    "terrain_type": "grass",
    "include_assets": true,
    "style": "cartoon"
  }'

Example Response

json

{
  "id": "itm_x9y8z7w6",
  "status": "complete",
  "map": {
    "size": 2048,
    "terrain_material": "Grass",
    "regions": [
      { "type": "water", "x": 0, "z": 0, "width": 256, "depth": 512 },
      { "type": "forest", "x": 256, "z": 0, "width": 512, "depth": 512 }
    ],
    "asset_placements": [
      { "asset_id": "7483950123", "name": "Oak Tree", "x": 300, "y": 0, "z": 150 }
    ]
  },
  "plugin_import_url": "https://api.forjegames.com/imports/itm_x9y8z7w6",
  "created_at": "2026-03-28T12:00:00Z"
}

POST/api/ai/generate

General-purpose AI generation endpoint. Provide a prompt and output type to generate Luau scripts, UI layouts, economy configs, NPC dialogue, or map blueprints from a text description.

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Natural language description of what to generate. Be specific — include genre, mechanics, and style.
`output_type`	`string`	Required	"script" \| "ui" \| "map" \| "dialogue" \| "economy". Determines the output schema.
`model`	`string`	Optional	Model to use: "fast" (lower latency) \| "quality" (higher fidelity). Defaults to "quality".
`max_tokens`	`number`	Optional	Maximum output tokens. Range: 256–8192. Defaults to 2048.
`context`	`string`	Optional	Existing code or context the model should build on or stay consistent with.

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/generate \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A leaderboard script that tracks player coins and updates every 5 seconds",
    "output_type": "script",
    "model": "quality",
    "max_tokens": 2048
  }'

Example Response

json

{
  "id": "gen_p5q6r7s8",
  "status": "complete",
  "output_type": "script",
  "result": {
    "code": "local Players = game:GetService(\"Players\")\nlocal RunService = game:GetService(\"RunService\")\n-- leaderboard logic...",
    "language": "luau",
    "tokens_used": 712,
    "warnings": []
  },
  "model": "quality",
  "created_at": "2026-03-28T12:00:00Z"
}

GET/api/marketplace/search

Search the Roblox marketplace for assets. Returns models, meshes, decals, audio, and plugins with metadata. All parameters are passed as query string values.

Parameters

Parameter	Type	Required	Description
`q`	`string`	Required	Search query string.
`category`	`string`	Optional	"model" \| "mesh" \| "decal" \| "audio" \| "plugin". Omit to search all categories.
`limit`	`number`	Optional	Number of results per page. Max 50. Defaults to 20.
`cursor`	`string`	Optional	Pagination cursor returned by the previous response.
`sort`	`string`	Optional	Sort order: "relevance" \| "updated" \| "favorites". Defaults to "relevance".
`free_only`	`boolean`	Optional	When true, only returns free assets.

Example Request

bash

curl -X GET "https://api.forjegames.com/api/marketplace/search" \
  -H "Authorization: Bearer fg_sk_..." \
  -G \
  --data-urlencode "q=low poly tree" \
  --data-urlencode "category=model" \
  --data-urlencode "limit=10" \
  --data-urlencode "free_only=true"

Example Response

json

{
  "results": [
    {
      "asset_id": "7483950123",
      "name": "Low Poly Oak Tree",
      "category": "model",
      "creator": "NatureAssets",
      "description": "A simple low-poly oak tree. 48 polygons.",
      "thumbnail_url": "https://tr.rbxcdn.com/abc123/150/150/Image/Png",
      "marketplace_url": "https://www.roblox.com/catalog/7483950123",
      "is_free": true,
      "favorites": 14200,
      "updated_at": "2025-11-04T09:32:00Z"
    }
  ],
  "total": 342,
  "has_more": true,
  "next_cursor": "eyJwIjoxfQ=="
}

SDKs

Official client libraries handle authentication, retries, and response parsing automatically.

TypeScript / Node.js

Node 18+

bash

npm install @forjegames/sdk

bash

import { ForjeGames } from '@forjegames/sdk'

const fg = new ForjeGames({ apiKey: process.env.FG_API_KEY })

const result = await fg.ai.generate({
  prompt: 'A coin shop UI with 3 items',
  output_type: 'ui',
})

Python

Python 3.9+

bash

pip install forjegames

bash

import forjegames

fg = forjegames.Client(api_key=os.environ["FG_API_KEY"])

result = fg.ai.generate(
    prompt="A coin shop UI with 3 items",
    output_type="ui",
)

Rate Limits

Limits are enforced per API key. Current usage is exposed via response headers on every request.

Plan	Req / min	Req / day	AI calls / day	Concurrent
Free	30	500	10	1
Hobby	60	5,000	100	3
Creator	300	50,000	1,000	10
Studio	600	Unlimited	Unlimited	25

Rate Limit Headers

`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining before the limit resets
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

Errors

All errors return a consistent JSON body with a machine-readable code and a human-readable message.

Error Response Shape

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401,
    "request_id": "req_2b3c4d5e"
  }
}

Status	Error Code	Description
400	`invalid_request`	Missing or malformed request parameters.
401	`invalid_api_key`	API key is missing, invalid, or revoked.
403	`insufficient_scope`	The key exists but lacks the required scope for this endpoint.
404	`not_found`	The requested resource does not exist.
409	`conflict`	Request conflicts with existing state (e.g. duplicate resource).
422	`unprocessable`	Request is well-formed but semantically invalid.
429	`rate_limit_exceeded`	Too many requests. Check Retry-After header.
500	`internal_error`	Unexpected server error. Retry with exponential backoff.
503	`service_unavailable`	Temporary downtime or maintenance. Check status.forjegames.com.

ForjeGames

Getting Started

Base URL

json

https://api.forjegames.com

1. Get an API key

Sign in to your dashboard and navigate to Settings → API Keys to create a key. The raw key is shown once — save it immediately.

2. Make your first request

bash

curl -X GET https://api.forjegames.com/api/marketplace/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -G --data-urlencode "q=sword"

Authentication

All API requests must be authenticated with a Bearer token in the Authorization header. API keys are prefixed with fg_sk_.

Request Header

bash

Authorization: Bearer fg_sk_your_api_key_here

Security: Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests only.

Endpoints

All endpoints accept and return application/json.

POST/api/ai/voice-to-game

Convert a voice recording or transcript into a Roblox Luau game script. The AI interprets natural language commands and generates structured game logic, event handlers, and UI elements.

Parameters

Parameter	Type	Required	Description
`audio_url`	`string`	Optional	Publicly accessible URL of an audio file (mp3, wav, ogg, webm). Provide either this or transcript.
`transcript`	`string`	Optional	Pre-transcribed text to convert. Used when audio_url is not provided.
`language`	`string`	Optional	BCP-47 language code for transcription. Defaults to "en-US".
`style`	`string`	Optional	Output style hint: "simulator" \| "obby" \| "roleplay" \| "generic". Helps the model target the correct game genre.
`include_ui`	`boolean`	Optional	When true, the response includes ScreenGui XML alongside the Luau script.

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/voice-to-game \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/recording.mp3",
    "style": "simulator",
    "include_ui": true
  }'

Example Response

json

{
  "id": "vtg_a1b2c3d4",
  "status": "complete",
  "transcript": "Create a shop button that opens a store menu with three items",
  "output": {
    "script": "local Players = game:GetService(\"Players\")\n-- generated Luau...",
    "ui_xml": "<ScreenGui>...</ScreenGui>",
    "tokens_used": 1840
  },
  "created_at": "2026-03-28T12:00:00Z"
}

POST/api/ai/image-to-map

Parameters

Parameter	Type	Required	Description
`image_url`	`string`	Required	Publicly accessible URL of the source image (jpg, png, webp). Max 10 MB.
`map_size`	`number`	Optional	Target map width in studs. Accepted values: 512, 1024, 2048, 4096. Defaults to 1024.
`terrain_type`	`string`	Optional	Dominant terrain material: "grass" \| "sand" \| "snow" \| "rock" \| "mud". Defaults to "grass".
`include_assets`	`boolean`	Optional	When true, the response embeds marketplace asset IDs for auto-placement.
`style`	`string`	Optional	Visual style hint: "realistic" \| "cartoon" \| "lowpoly".

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/image-to-map \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.example.com/concept-art.png",
    "map_size": 2048,
    "terrain_type": "grass",
    "include_assets": true,
    "style": "cartoon"
  }'

Example Response

json

{
  "id": "itm_x9y8z7w6",
  "status": "complete",
  "map": {
    "size": 2048,
    "terrain_material": "Grass",
    "regions": [
      { "type": "water", "x": 0, "z": 0, "width": 256, "depth": 512 },
      { "type": "forest", "x": 256, "z": 0, "width": 512, "depth": 512 }
    ],
    "asset_placements": [
      { "asset_id": "7483950123", "name": "Oak Tree", "x": 300, "y": 0, "z": 150 }
    ]
  },
  "plugin_import_url": "https://api.forjegames.com/imports/itm_x9y8z7w6",
  "created_at": "2026-03-28T12:00:00Z"
}

POST/api/ai/generate

General-purpose AI generation endpoint. Provide a prompt and output type to generate Luau scripts, UI layouts, economy configs, NPC dialogue, or map blueprints from a text description.

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Natural language description of what to generate. Be specific — include genre, mechanics, and style.
`output_type`	`string`	Required	"script" \| "ui" \| "map" \| "dialogue" \| "economy". Determines the output schema.
`model`	`string`	Optional	Model to use: "fast" (lower latency) \| "quality" (higher fidelity). Defaults to "quality".
`max_tokens`	`number`	Optional	Maximum output tokens. Range: 256–8192. Defaults to 2048.
`context`	`string`	Optional	Existing code or context the model should build on or stay consistent with.

Example Request

bash

curl -X POST https://api.forjegames.com/api/ai/generate \
  -H "Authorization: Bearer fg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A leaderboard script that tracks player coins and updates every 5 seconds",
    "output_type": "script",
    "model": "quality",
    "max_tokens": 2048
  }'

Example Response

json

{
  "id": "gen_p5q6r7s8",
  "status": "complete",
  "output_type": "script",
  "result": {
    "code": "local Players = game:GetService(\"Players\")\nlocal RunService = game:GetService(\"RunService\")\n-- leaderboard logic...",
    "language": "luau",
    "tokens_used": 712,
    "warnings": []
  },
  "model": "quality",
  "created_at": "2026-03-28T12:00:00Z"
}

GET/api/marketplace/search

Search the Roblox marketplace for assets. Returns models, meshes, decals, audio, and plugins with metadata. All parameters are passed as query string values.

Parameters

Parameter	Type	Required	Description
`q`	`string`	Required	Search query string.
`category`	`string`	Optional	"model" \| "mesh" \| "decal" \| "audio" \| "plugin". Omit to search all categories.
`limit`	`number`	Optional	Number of results per page. Max 50. Defaults to 20.
`cursor`	`string`	Optional	Pagination cursor returned by the previous response.
`sort`	`string`	Optional	Sort order: "relevance" \| "updated" \| "favorites". Defaults to "relevance".
`free_only`	`boolean`	Optional	When true, only returns free assets.

Example Request

bash

curl -X GET "https://api.forjegames.com/api/marketplace/search" \
  -H "Authorization: Bearer fg_sk_..." \
  -G \
  --data-urlencode "q=low poly tree" \
  --data-urlencode "category=model" \
  --data-urlencode "limit=10" \
  --data-urlencode "free_only=true"

Example Response

json

{
  "results": [
    {
      "asset_id": "7483950123",
      "name": "Low Poly Oak Tree",
      "category": "model",
      "creator": "NatureAssets",
      "description": "A simple low-poly oak tree. 48 polygons.",
      "thumbnail_url": "https://tr.rbxcdn.com/abc123/150/150/Image/Png",
      "marketplace_url": "https://www.roblox.com/catalog/7483950123",
      "is_free": true,
      "favorites": 14200,
      "updated_at": "2025-11-04T09:32:00Z"
    }
  ],
  "total": 342,
  "has_more": true,
  "next_cursor": "eyJwIjoxfQ=="
}

SDKs

Official client libraries handle authentication, retries, and response parsing automatically.

TypeScript / Node.js

Node 18+

bash

npm install @forjegames/sdk

bash

import { ForjeGames } from '@forjegames/sdk'

const fg = new ForjeGames({ apiKey: process.env.FG_API_KEY })

const result = await fg.ai.generate({
  prompt: 'A coin shop UI with 3 items',
  output_type: 'ui',
})

Python

Python 3.9+

bash

pip install forjegames

bash

import forjegames

fg = forjegames.Client(api_key=os.environ["FG_API_KEY"])

result = fg.ai.generate(
    prompt="A coin shop UI with 3 items",
    output_type="ui",
)

Rate Limits

Limits are enforced per API key. Current usage is exposed via response headers on every request.

Plan	Req / min	Req / day	AI calls / day	Concurrent
Free	30	500	10	1
Hobby	60	5,000	100	3
Creator	300	50,000	1,000	10
Studio	600	Unlimited	Unlimited	25

Rate Limit Headers

`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining before the limit resets
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

Errors

All errors return a consistent JSON body with a machine-readable code and a human-readable message.

Error Response Shape

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401,
    "request_id": "req_2b3c4d5e"
  }
}

Status	Error Code	Description
400	`invalid_request`	Missing or malformed request parameters.
401	`invalid_api_key`	API key is missing, invalid, or revoked.
403	`insufficient_scope`	The key exists but lacks the required scope for this endpoint.
404	`not_found`	The requested resource does not exist.
409	`conflict`	Request conflicts with existing state (e.g. duplicate resource).
422	`unprocessable`	Request is well-formed but semantically invalid.
429	`rate_limit_exceeded`	Too many requests. Check Retry-After header.
500	`internal_error`	Unexpected server error. Retry with exponential backoff.
503	`service_unavailable`	Temporary downtime or maintenance. Check status.forjegames.com.