> For the complete documentation index, see [llms.txt](https://juber.gitbook.io/bbb-guides/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://juber.gitbook.io/bbb-guides/docs.md).

# docs

## Authentication

All Application API endpoints require a Pterodactyl Application API key.

1. Go to your Pterodactyl Admin Panel -> **Application API**.
2. Create a key with **Servers** (Read/Write) permissions.
3. Pass the key in the headers of your HTTP requests:

```http
Authorization: Bearer ptla_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Accept: application/json
Content-Type: application/json
```

## Endpoints (Application API)

### 1. List Available Root Domains

Fetch a list of all custom domains you have configured in the Subdomain Manager admin panel. You will need the `domain_id` to create subdomains.

* **URL:** `GET /api/application/subdomainmanager/domains`
* **Response (200 OK):**

```json
{
  "object": "list",
  "data": [
    {
      "id": 1,
      "domain": "subeditor.works",
      "description": "",
      "created_at": null
    }
  ]
}
```

### 2. Check Subdomain Availability

Check whether a specific string is available to be registered, or if it is already taken by another server.

* **URL:** `GET /api/application/subdomainmanager/servers/{server_id}/subdomains/check`
* **Query Parameters:**
  * `subdomain` (string): The requested prefix.
  * `domain_id` (integer): The ID of the root domain.
* **Example:** `/check?subdomain=play&domain_id=1`
* **Response (200 OK - Available):**

```json
{
  "available": true,
  "message": "This subdomain is available."
}
```

* **Response (200 OK - Taken):**

```json
{
  "available": false,
  "message": "This subdomain is already taken."
}
```

### 3. Create a Subdomain

Create a new subdomain for a specific server. This will automatically contact Cloudflare to generate the `A` and `SRV` records, and will assign it in the Pterodactyl database.

* **URL:** `POST /api/application/subdomainmanager/servers/{server_id}/subdomains`
* **Body:**

```json
{
  "domain_id": 1,
  "allocation_id": 7,
  "subdomain": "play"
}
```

*(Note: `allocation_id` is the ID of the specific port allocation you want the SRV record to point to. You can fetch a server's allocations via the standard Pterodactyl API).*

* **Response (201 Created):**

```json
{
  "object": "subdomain",
  "attributes": {
    "id": 19,
    "server_id": 12,
    "domain_id": 1,
    "allocation_id": 7,
    "subdomain": "play",
    "full_domain": "play.subeditor.works",
    "port": 25565,
    "record_type": "A+SRV"
  }
}
```

* **Error Responses:**
  * `400 Bad Request` if the server has reached its subdomain limit.
  * `422 Unprocessable Entity` if the subdomain name is invalid (too short/long or hits blocked regex).

### 4. Delete a Subdomain

Delete an existing subdomain. This will automatically wipe the `A` and `SRV` records from Cloudflare and delete the entry from the database.

* **URL:** `DELETE /api/application/subdomainmanager/servers/{server_id}/subdomains/{record_id}`
* **Response (204 No Content):** (Empty body, successful deletion).

## Client API (Internal)

If you are developing a custom Pterodactyl frontend rather than an external billing panel, you should use the **Client API** endpoints instead, which authenticate via the user's `ptlc_` token.

**Base URL:** `/api/client/servers/{server_uuid}/subdomainmanager`

*Note: Client API uses the Server UUID (e.g. `b6a04737-...`), while the Application API uses the integer Server ID (e.g. `12`).*

* `GET /` - List user's created subdomains, allowed domains, and the subdomain limit.
* `POST /` - Create a subdomain (Accepts `domain`, `subdomain`, `allocation`).
* `PATCH /{record_id}` - Update the allocation tied to an existing subdomain.
* `DELETE /{record_id}` - Delete a subdomain.

## Billing Panel Example Workflow (WHMCS)

If you want to offer a free subdomain when a customer buys a Minecraft server:

1. **After Server Creation:** Your WHMCS module queries the Pterodactyl Application API to get the new server's integer ID (`id`) and primary Allocation ID (`allocation_id`).
2. **Check Name:** Optional—the user inputs their desired subdomain at checkout. WHMCS hits the `GET /check` endpoint.
3. **Provision:** WHMCS fires a `POST /subdomains` request with the `domain_id` (your default domain), the server's `allocation_id`, and the `subdomain` string the user requested.
4. **Done!** The user's server now has a Cloudflare DNS record instantly pointing to their IP and port.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://juber.gitbook.io/bbb-guides/docs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.