Skip to main content

​
List Blueprints

GET /api/blueprints
Authorization: Bearer {token}
List all blueprints. Users see public blueprints, admins see all.

​
Authentication

Requires authentication.

​
Response

​
blueprints
array
Array of blueprint objects
[
  {
    "id": "minecraft-java",
    "name": "Minecraft Java",
    "description": "Vanilla Minecraft Java Edition",
    "category": "minecraft",
    "author": "StellarStack",
    "metaVersion": "PTDL_v2",
    "dockerImages": {
      "Java 21": "ghcr.io/pterodactyl/yolks:java_21",
      "Java 17": "ghcr.io/pterodactyl/yolks:java_17"
    },
    "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
    "config": {
      "stop": "stop",
      "startup": {
        "done": ["Done ("]
      }
    },
    "variables": [
      {
        "name": "Minecraft Version",
        "description": "The version of Minecraft to download",
        "env_variable": "MINECRAFT_VERSION",
        "default_value": "latest",
        "user_viewable": true,
        "user_editable": true,
        "rules": "required|string"
      }
    ],
    "features": ["eula"],
    "fileDenylist": [],
    "isPublic": true
  }
]

​
Get Blueprint

GET /api/blueprints/{id}
Authorization: Bearer {token}
Get detailed information about a specific blueprint.

​
Path Parameters

​
id
string
required
Blueprint UUID

​
Authentication

Requires authentication. Non-admins can only view public blueprints.

​
Response

Returns a detailed blueprint object.

​
Errors

  • 404 - Blueprint not found or not public (for non-admins)

​
Create Blueprint

POST /api/blueprints
Authorization: Bearer {token}
Content-Type: application/json
Create a new blueprint. Admin only.

​
Authentication

Requires admin role.

​
Request Body

​
name
string
required
Blueprint name (1-100 characters)
​
description
string
Blueprint description
​
category
string
Category (e.g., “minecraft”, “voice”, “other”)
​
author
string
Author name
​
dockerImages
object
default:"{}"
Docker images as key-value pairs (label -> image)
​
startup
string
default:""
Startup command template with variable substitution
​
config
object
Configuration object (stop command, startup detection, etc.)
​
scripts
object
Installation scripts object
​
variables
array
Environment variable definitions
​
features
array
Feature flags array
​
fileDenylist
array
default:"[]"
File patterns to block
​
dockerConfig
object
Docker container configuration
​
isPublic
boolean
default:"true"
Whether blueprint is publicly visible
{
  "name": "Custom Minecraft",
  "description": "Custom modded Minecraft server",
  "category": "minecraft",
  "author": "MyOrg",
  "dockerImages": {
    "Java 21": "ghcr.io/pterodactyl/yolks:java_21"
  },
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar server.jar",
  "config": {
    "stop": "stop",
    "startup": {
      "done": ["Done ("]
    }
  },
  "variables": [
    {
      "name": "Server JAR",
      "env_variable": "SERVER_JARFILE",
      "default_value": "server.jar",
      "user_viewable": true,
      "user_editable": true
    }
  ],
  "features": ["eula"],
  "fileDenylist": [],
  "isPublic": true
}

​
Response

Returns the created blueprint object with status 201.

​
Errors

  • 400 - Validation failed

​
Update Blueprint

PATCH /api/blueprints/{id}
Authorization: Bearer {token}
Content-Type: application/json
Update an existing blueprint. Admin only.

​
Path Parameters

​
id
string
required
Blueprint UUID

​
Authentication

Requires admin role.

​
Request Body

All fields are optional. Only include fields you want to update.

​
Response

Returns the updated blueprint object.

​
Errors

  • 400 - Validation failed
  • 404 - Blueprint not found

​
Delete Blueprint

DELETE /api/blueprints/{id}
Authorization: Bearer {token}
Delete a blueprint. Cannot delete blueprints in use by servers. Admin only.

​
Path Parameters

​
id
string
required
Blueprint UUID

​
Authentication

Requires admin role.

​
Response

{ "success": true }

​
Errors

  • 400 - Blueprint is in use by servers
  • 404 - Blueprint not found

​
Import Pterodactyl Egg

POST /api/blueprints/import/egg
Authorization: Bearer {token}
Content-Type: application/json
Import a Pterodactyl egg JSON file as a blueprint. Admin only.

​
Authentication

Requires admin role.

​
Request Body

Provide the complete Pterodactyl egg JSON object.
​
name
string
required
Egg name
​
author
string
Egg author
​
description
string
Egg description
​
meta
object
Metadata object with version and update_url
​
docker_images
object
Docker images object
​
startup
string
Startup command
​
config
object
Configuration object
​
scripts
object
Installation scripts
​
variables
array
Variable definitions
​
features
array
Feature flags
​
file_denylist
array
File denylist
{
  "meta": {
    "version": "PTDL_v2",
    "update_url": null
  },
  "name": "Minecraft",
  "author": "[email protected]",
  "description": "Minecraft Java Edition",
  "features": ["eula"],
  "docker_images": {
    "Java 21": "ghcr.io/pterodactyl/yolks:java_21"
  },
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
  "config": {
    "stop": "stop",
    "startup": {
      "done": ["Done ("]
    }
  },
  "scripts": {
    "installation": {
      "script": "#!/bin/bash\n# Install script here",
      "container": "ghcr.io/pterodactyl/installers:alpine"
    }
  },
  "variables": [
    {
      "name": "Minecraft Version",
      "env_variable": "MINECRAFT_VERSION",
      "default_value": "latest",
      "user_viewable": true,
      "user_editable": true
    }
  ]
}

​
Response

​
success
boolean
Always true on success
​
blueprint
object
The created blueprint object
​
message
string
Success message
{
  "success": true,
  "blueprint": {
    "id": "imported-minecraft",
    "name": "Minecraft",
    "category": "imported",
    "author": "[email protected]"
  },
  "message": "Successfully imported \"Minecraft\" from Pterodactyl egg"
}

​
Errors

  • 400 - Invalid Pterodactyl egg format

​
Export as Pterodactyl Egg

GET /api/blueprints/{id}/export/egg
Authorization: Bearer {token}
Export a blueprint as Pterodactyl egg JSON format. Admin only.

​
Path Parameters

​
id
string
required
Blueprint UUID

​
Authentication

Requires admin role.

​
Response

Returns a Pterodactyl egg JSON object. 
{
  "_comment": "EXPORTED FROM STELLARSTACK",
  "meta": {
    "version": "PTDL_v2",
    "update_url": null
  },
  "exported_at": "2024-01-15T12:00:00Z",
  "name": "Minecraft Java",
  "author": "StellarStack",
  "description": "Vanilla Minecraft Java Edition",
  "features": ["eula"],
  "docker_images": {
    "Java 21": "ghcr.io/pterodactyl/yolks:java_21"
  },
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
  "config": {
    "stop": "stop"
  },
  "scripts": {},
  "variables": [],
  "file_denylist": []
}

​
Errors

  • 404 - Blueprint not found

Build docs developers (and LLMs) love

Get started for freeTalk to us