To request a subdomain, you need to create a JSON configuration file that tells us how your subdomain should behave.

Each configuration file is added to the domains/ directory in the repository and must follow specific naming conventions.

​
Filename Requirements

Your configuration file must meet these criteria:

  • Must be alphanumeric, in lowercase
  • Dashes (-) may be used as separators
  • Must be at least 1 character long
  • Must have a .json file extension
  • Must not contain the parent domain name

​
Invalid Filename Examples

  • .json (filename is less than 1 character)
  • A.json (contains uppercase letters)
  • a..json (contains consecutive dots)
  • .a.json (starts with a dot)
  • a .json (contains a space)
  • a$.json (contains non-alphanumeric character)
  • a.json.json (multiple .json extensions)

​
Valid Filename Examples

  • a.json (at least 1 character long)
  • example.json (alphanumeric and lowercase)
  • blog.example.json (includes dots for sub-subdomains)
  • my-blog.json (uses dashes as separators)

Note: To prevent monopolization, users are limited to one one-letter subdomain.

​
Basic Structure

Here’s what a minimal configuration looks like:

{
  "description": "My personal website",
  "repo": "https://github.com/username/repo",
  "owner": {
    "username": "your-github-username",
    "email": "yourname@example.com"
  },
  "records": {
    "CNAME": "username.github.io"
  },
  "proxied": false
}

​
Required Fields

​
owner

Information about the domain owner. This is required for communication if needed.

{
  "owner": {
    "username": "your-github-username",
    "email": "yourname@example.com"
  }
}

​
records

Defines the DNS records for your subdomain. At least one record type is required.

​
Optional Fields

​
description

A brief description of your domain’s purpose (optional but recommended).

​
repo

Link to your website’s repository or GitHub account (optional).

​
proxied

Enable Cloudflare proxying for your domain (defaults to false).

{
  "proxied": true
}

​
Supported DNS Records

​
CNAME Record

Points your domain to another hostname.

{
  "records": {
    "CNAME": "username.github.io"
  }
}

​
A Record

Maps your domain to IPv4 addresses.

{
  "records": {
    "A": [
      "192.0.2.1",
      "198.51.100.1"
    ]
  }
}

​
AAAA Record

Maps your domain to IPv6 addresses.

{
  "records": {
    "AAAA": [
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
    ]
  }
}

​
MX Record

Specifies mail servers for your domain.

{
  "records": {
    "MX": [
      {
        "target": "mx1.example.com",
        "priority": 10
      },
      {
        "target": "mx2.example.com",
        "priority": 20
      }
    ]
  }
}

​
TXT Record

Stores text information, often used for verification.

{
  "records": {
    "TXT": ["v=spf1 include:_spf.example.com ~all"]
  }
}

​
SRV Record

Defines service locations (e.g., VoIP, messaging, gaming servers).

{
  "records": {
    "SRV": [
      {
        "priority": 10,
        "weight": 5,
        "port": 8080,
        "target": "srv.example.com"
      }
    ]
  }
}

​
CAA Record

Controls which Certificate Authorities can issue SSL certificates.

{
  "records": {
    "CAA": [
      {
        "flags": 0,
        "tag": "issue",
        "value": "letsencrypt.org"
      }
    ]
  }
}

​
Important Notes

  • Each domain requires its own configuration file
  • JSON must be valid - use a JSON validator if needed
  • Your subdomain request will be reviewed before approval
  • You can update your configuration by submitting a new pull request
  • Some record combinations may have restrictions (e.g., CNAME with other records)

Need help? Visit our Get Started guide or open an issue.