docs · updated 2026-05-16

API reference

The public REST API for the hatchery.pet catalog, manifests, and install telemetry.

What this documents

The public REST API at hatchery.pet/api. Use it to read the catalog, fetch install manifests, and record install events from custom clients. Catalog reads need no authentication; install events use IP-hash rate limiting.

Read the catalog

Catalog reads return stable pet IDs, slugs, rarity, summary copy, preview sprite URLs, and manifest URLs. List responses are cached for five minutes.

bashcatalog

curl https://hatchery.pet/api/pets

Install from manifests

The manifest is the installer contract. It includes the pet ID, install command, state sprite URLs, animation hints, creator attribution, license, and detail links. Pet and manifest responses are cached for one hour.

bashmanifest

curl https://hatchery.pet/api/pets/claw/manifest

jsoncshape

{
  "schemaVersion": "1.0.0",
  "id": "pet_claw",
  "slug": "claw",
  "name": "Claw",
  "installCommand": "npx hatchery-pet install claw",
  "sprites": {
    "idle": "/pets/claw/spritesheet.webp",
    "thinking": "/pets/claw/spritesheet.webp",
    "working": "/pets/claw/spritesheet.webp",
    "celebrating": "/pets/claw/spritesheet.webp"
  }
}

Record installs

Install clients post source and version after a successful write. The endpoint accepts open CORS, hashes IP addresses before storage, and limits each IP hash to 100 events per hour.

bashinstall-event

curl -X POST https://hatchery.pet/api/pets/claw/install-event \
-H-H "content-type: application/json" \
-d-d '{"source":"cli","version":"1.0.0"}'

bashopenapi

curl https://hatchery.pet/api/openapi.json

Error responses

API errors use short codes, plain messages, and request IDs. They do not include sales copy or surprise redirects.