← Back to Generator

API Documentation

Generate petnames programmatically via a simple HTTP API

Endpoint

Returns a randomly generated petname as plain text.

Query Parameters

Parameter	Type	Default	Description
words	integer	2	Number of words in the petname (1, 2, or 3). Values outside this range are clamped.
separator	string	-	String used to separate words in the petname.

Response

The response is plain text (text/plain) containing a single petname followed by a newline.

Examples

Default (2-word petname)

Request:

curl https://petname.moles.dev/api

Response:

brave-falcon

Single word (animal name only)

Request:

curl "https://petname.moles.dev/api?words=1"

Response:

penguin

Three words (adverb-adjective-animal)

Request:

curl "https://petname.moles.dev/api?words=3"

Response:

deeply-brave-falcon

Custom separator

Request:

curl "https://petname.moles.dev/api?words=3&separator=_"

Response:

gladly_noble_tiger

Use in scripts

Assign to a variable:

NAME=$(curl -s https://petname.moles.dev/api)
echo "New server name: $NAME"

Slack Integration

Use petname as a Slack slash command to generate names directly in Slack. The result is shown only to you (ephemeral), so you can copy and use it without posting to the channel.

Setup

To add /petname to your Slack workspace:

1. Go to api.slack.com/apps and create a new app
2. Navigate to Slash Commands and create a new command
3. Set the command to /petname
4. Set the Request URL to https://petname.moles.dev/api/slack
5. Install the app to your workspace

Usage

Default (2-word petname):

/petname

Response (only visible to you):

brave-falcon

Specify word count:

/petname 3

Response:

deeply-brave-falcon

Custom separator:

/petname 2 _

Response:

noble_tiger