FAQ and answers about naming conventions for rocks.

Naming Conventions for Rocks

A rock's name is used in API URLs, dashboard headers, billing line items, and webhook payloads. Choosing a clear, compliant name from the start avoids the need to migrate references later.

Technical requirements

Rock names must conform to the following rules:

  • Length between 3 and 63 characters
  • Lowercase ASCII letters, digits, and hyphens only (a-z, 0-9, -)
  • Must begin and end with a letter or digit
  • Must not contain consecutive hyphens (--)
  • Must be unique within your workspace

These rules align with RFC 1123 hostname requirements, since rock names are used as DNS subdomains in our public API.

Valid examples

  • granite-1
  • desk-rock
  • marble-prod-eu

Invalid examples

  • Rocky (uppercase letters)
  • my_rock (underscore not permitted)
  • -pebble (begins with a hyphen)
  • r (too short)

Reserved names

The following names are reserved by the platform and cannot be assigned:

  • admin, system, internal
  • Any name beginning with petrock- or ms-
  • Any name matching a region identifier (e.g., us-east-stone-1)

If you attempt to provision a rock with a reserved name, the API will return a 409 Conflict error.

Best practices

Use a consistent prefix or suffix

If you manage multiple rocks, prefixes such as prod- or staging- make filtering in the dashboard significantly easier.

Avoid embedding sensitive information

Rock names appear in webhook payloads and audit logs. Do not include customer identifiers, internal project codenames, or anything you would not want to appear in a third-party Slack workspace.

Plan for scale

If you intend to autoscale, use a base name that anticipates numerical suffixes. For example, granite-01 rather than granite, since the autoscaler will append -02, -03, etc.

Renaming a rock

Rocks can be renamed from Settings → General → Rock Identity. Note the following:

Warning: Renaming a rock changes its API endpoint URL. Existing webhook URLs and integrations that reference the old name will continue to receive nothing, as they did before, but they will receive nothing under the old name rather than the new one. Update integrations accordingly.

The previous name is reserved for 30 days after a rename to prevent typosquatting within your workspace.