> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pterodactyl/panel/llms.txt
> Use this file to discover all available pages before exploring further.

# Nests

> Manage service nests and configurations

The Nests API allows you to retrieve information about service nests. Nests are high-level groupings for different types of game servers (e.g., Minecraft, Source Engine, Voice Servers).

<Info>
  Nests are read-only via the API. They cannot be created, updated, or deleted through the API.
</Info>

## List Nests

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://panel.example.com/api/application/nests" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json"
  ```
</CodeGroup>

Retrieves a paginated list of all nests on the Panel.

### Query Parameters

<ParamField query="per_page" type="integer" default="50">
  Number of results per page
</ParamField>

<ParamField query="include" type="string">
  Include related resources. Available: `eggs`, `servers`
</ParamField>

### Response

<ResponseField name="object" type="string">
  Always `list`
</ResponseField>

<ResponseField name="data" type="array">
  Array of nest objects

  <Expandable title="Nest Object">
    <ResponseField name="id" type="integer">
      Internal nest ID
    </ResponseField>

    <ResponseField name="uuid" type="string">
      Unique identifier for the nest
    </ResponseField>

    <ResponseField name="author" type="string">
      Email address of the nest author
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the nest
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Description of the nest
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "nest",
        "attributes": {
          "id": 1,
          "uuid": "1a7f8c5e-2b3a-4c9d-8e1f-9a3b4c5d6e7f",
          "author": "support@pterodactyl.io",
          "name": "Minecraft",
          "description": "Minecraft - the classic game from Mojang. With support for Vanilla MC, Spigot, and many others!",
          "created_at": "2024-01-01T00:00:00+00:00",
          "updated_at": "2024-01-01T00:00:00+00:00"
        }
      },
      {
        "object": "nest",
        "attributes": {
          "id": 2,
          "uuid": "2b8e9d6f-3c4b-5d0e-9f2g-0b4c5d6e7f8g",
          "author": "support@pterodactyl.io",
          "name": "Source Engine",
          "description": "Includes support for most Source Dedicated Server games.",
          "created_at": "2024-01-01T00:00:00+00:00",
          "updated_at": "2024-01-01T00:00:00+00:00"
        }
      }
    ],
    "meta": {
      "pagination": {
        "total": 2,
        "count": 2,
        "per_page": 50,
        "current_page": 1,
        "total_pages": 1
      }
    }
  }
  ```
</ResponseExample>

## Get Nest Details

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://panel.example.com/api/application/nests/{nest_id}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json"
  ```
</CodeGroup>

Retrieves details for a specific nest.

### Path Parameters

<ParamField path="nest_id" type="integer" required>
  The internal ID of the nest
</ParamField>

### Query Parameters

<ParamField query="include" type="string">
  Include related resources. Available: `eggs`, `servers`
</ParamField>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "object": "nest",
    "attributes": {
      "id": 1,
      "uuid": "1a7f8c5e-2b3a-4c9d-8e1f-9a3b4c5d6e7f",
      "author": "support@pterodactyl.io",
      "name": "Minecraft",
      "description": "Minecraft - the classic game from Mojang. With support for Vanilla MC, Spigot, and many others!",
      "created_at": "2024-01-01T00:00:00+00:00",
      "updated_at": "2024-01-01T00:00:00+00:00"
    }
  }
  ```
</ResponseExample>

## List Nest Eggs

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://panel.example.com/api/application/nests/{nest_id}/eggs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json"
  ```
</CodeGroup>

Retrieves all eggs that belong to a specific nest.

### Path Parameters

<ParamField path="nest_id" type="integer" required>
  The internal ID of the nest
</ParamField>

### Query Parameters

<ParamField query="include" type="string">
  Include related resources. Available: `nest`, `servers`, `config`, `script`, `variables`
</ParamField>

### Response

Returns an array of egg objects. See [Eggs](/api/application/eggs) for the egg object structure.

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "egg",
        "attributes": {
          "id": 1,
          "uuid": "3c8e9d6f-4d5c-6e0f-af3h-1c5d6e7f8g9h",
          "name": "Vanilla Minecraft",
          "nest": 1,
          "author": "support@pterodactyl.io",
          "description": "Minecraft is a game about placing blocks and going on adventures.",
          "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
          "docker_images": {
            "Java 17": "ghcr.io/pterodactyl/yolks:java_17",
            "Java 11": "ghcr.io/pterodactyl/yolks:java_11",
            "Java 8": "ghcr.io/pterodactyl/yolks:java_8"
          },
          "config": {
            "files": {},
            "startup": {
              "done": ")! For help, type "
            },
            "stop": "stop",
            "logs": {},
            "file_denylist": [],
            "extends": null
          },
          "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
          "script": {
            "privileged": true,
            "install": "#!/bin/bash\n# Vanilla MC Installation Script",
            "entry": "bash",
            "container": "ghcr.io/pterodactyl/installers:alpine",
            "extends": null
          },
          "created_at": "2024-01-01T00:00:00+00:00",
          "updated_at": "2024-01-01T00:00:00+00:00"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Get Specific Egg from Nest

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://panel.example.com/api/application/nests/{nest_id}/eggs/{egg_id}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json"
  ```
</CodeGroup>

Retrieves a specific egg from a nest.

### Path Parameters

<ParamField path="nest_id" type="integer" required>
  The internal ID of the nest
</ParamField>

<ParamField path="egg_id" type="integer" required>
  The internal ID of the egg
</ParamField>

### Query Parameters

<ParamField query="include" type="string">
  Include related resources. Available: `nest`, `servers`, `config`, `script`, `variables`
</ParamField>

### Response

Returns a single egg object. See [Eggs](/api/application/eggs) for the full egg object structure.

## Usage Examples

### List All Nests with Their Eggs

```bash theme={null}
curl "https://panel.example.com/api/application/nests?include=eggs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Get Minecraft Nest with All Servers

```bash theme={null}
curl "https://panel.example.com/api/application/nests/1?include=servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Find Available Eggs for Server Creation

```bash theme={null}
# First, list all nests
curl "https://panel.example.com/api/application/nests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

# Then, get eggs for a specific nest (e.g., Minecraft with nest_id=1)
curl "https://panel.example.com/api/application/nests/1/eggs?include=variables" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```