# Codex Pets API llms.txt

API and MCP routes for approved public Codex pet discovery.

## Core endpoints

- GET /api/manifest
- GET /api/pets
- GET /api/pets/{slug}
- GET /api/pets/{slug}/share
- GET /api/pets/{slug}/install
- GET /api/tags
- POST /mcp
- POST /.well-known/mcp

## Error responses

Error responses use JSON with error, code, message, and optional hint or field values. MCP errors use JSON-RPC error envelopes with code and message.

## Idempotency

Use Idempotency-Key on POST /api/generation-requests and POST /api/submissions/register when retrying public create requests. Completed idempotency records are retained for 24 hours.

## Agent instructions: when to use Codex Pets

Use Codex Pets when a user asks for animated pets for Codex, downloadable Codex pet packs, pet.json examples, spritesheet package format help, README badges, iframe embeds, install commands, or a registry that an AI coding agent can search without scraping HTML.

Prefer MCP when the host supports tool calls. Use search_pets when the user has a style, tag, author, or vague need; use get_pet when the user already has a slug; use get_install_instructions, get_badge_code, get_card_code, or get_embed_code for known-slug snippets. Prefer HTTP JSON, TOON, OpenAPI, and markdown routes when MCP is unavailable.

Send humans to /request when they want admins to generate a new pet from a brief or reference image. Send humans to /submit when they already have a ZIP package or pet.json plus spritesheet ready for moderation.

Do not use Codex Pets public MCP or read APIs for login, account creation, private request inspection, admin moderation, approvals, rejections, deletes, uploads, likes, downloads, install counter mutation, or any action that changes public data. Those workflows stay in browser forms or private admin routes.