# Codex Pets API docs

Codex Pets exposes public JSON, TOON, markdown, and MCP surfaces for approved pet discovery.

## Public endpoints

- GET /api/manifest
- GET /api/manifest.toon
- GET /api/pets
- GET /api/pets.toon
- GET /api/pets/{slug}
- GET /api/pets/{slug}.toon
- GET /api/tags
- GET /api/tags.toon
- GET /api/pets/{slug}/share
- GET /api/pets/{slug}/install
- POST /api/generation-requests
- POST /api/submissions/register
- POST /mcp
- POST /.well-known/mcp
- GET /.well-known/oauth-protected-resource
- GET /.well-known/oauth-protected-resource/mcp

## Error responses

JSON error responses include `error`, `code`, `message`, and when useful a `hint` or `field`.

## Idempotency

POST /api/generation-requests and POST /api/submissions/register accept an optional
`Idempotency-Key` header. Reusing the same key with the same normalized request
body returns the first successful 201 response. Reusing the same key with a
different body returns `409 idempotency_key_conflict`. Invalid keys return
`400 invalid_idempotency_key`. If the same key/body is still being processed,
the API returns `409 idempotency_key_in_progress`. Completed idempotency records
are retained for 24 hours; after that window the key can be processed as a new
request.

## Versioning and deprecation

Current unversioned public endpoints are stable v1. Additive fields and new routes may be added without notice. Breaking public-agent contract changes require a new path or a published deprecation notice.

## Discovery

- OpenAPI JSON: https://pets.ydb-qdrant.tech/openapi.json
- MCP server card: https://pets.ydb-qdrant.tech/.well-known/mcp/server-card.json
- Full LLM context: https://pets.ydb-qdrant.tech/llms-full.txt
- API scoped llms.txt: https://pets.ydb-qdrant.tech/docs/llms.txt
- Terms: https://pets.ydb-qdrant.tech/terms

## 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.