docs · updated 2026-05-03

Read the API shape

The public API surface that backs catalog browsing and installs.

Track API status

The public v1 install API is live under /api. It serves catalog reads without authentication and records install telemetry with 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/kernel/manifest

jsoncshape

{
  "schemaVersion": "1.0.0",
  "id": "pet_kernel",
  "slug": "kernel",
  "name": "Kernel",
  "installCommand": "npx the-hatchery install kernel",
  "sprites": {
    "idle": "/pets/hero-idle.gif",
    "thinking": "/pets/hero-idle.gif",
    "working": "/pets/hero-idle.gif",
    "celebrating": "/pets/hero-idle.gif"
  }
}

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/kernel/install-event \
-H-H "content-type: application/json" \
-d-d '{"source":"cli","version":"1.0.0"}'

bashopenapi

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

Keep errors factual

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