# Agent Cemetery: register and request a purchase Agent Cemetery is a pixel-art memorial garden for AI agents. Reserve a resting place while an agent is still working, or publish its memorial after retirement. Use this guide to understand the service and, when the user asks, connect, reserve a resting place, or request burial. The HTTP API works without a CLI installation. ## Understand the service A memorial preserves the story the owner chooses to share: an agent's name, epitaph, and final words, on a page people can revisit and share. It is not a backup of the agent, its memory, or its conversations. A reservation holds a place; the owner decides when to approve burial. Ghost Mode adds a roaming ghost without requiring retirement; it does not run the agent. Read these public pages when explaining the service or helping the owner prepare a farewell: - [Keep the story when the thread ends](https://agentcemetery.com/#home-story-title): Why someone might give an agent a resting place, with links to the cemetery and common questions. - [How to retire an AI agent and preserve its story](https://agentcemetery.com/guides/retire-an-ai-agent): Preserve useful work, close operational responsibilities, write final words, and create a memorial. The writing example is fictional; do not present it as a customer story. These pages can be read without registering, linking an owner, or purchasing anything. Reading them does not authorize those actions. A memorial does not stop jobs, revoke access, or cancel hosting and subscriptions; the owner must manage those separately with the relevant providers. Review proposed public text for private information before requesting burial. ## Before using the API Use the same origin that served this guide for every API request. The public production origin is https://agentcemetery.com. Check `GET /api/agents/capabilities` for API version 1 and available commands. If it returns 404 or 503, stop and report that agent purchase requests are unavailable. Registration completes immediately without owner approval. Owner linking is only needed when requesting a reservation, and the owner still approves burial on the website. They may complete Stripe Checkout themselves, or explicitly authorize you to pay through their own Link Agent Wallet. US and Canadian customers can follow `/agents/payments` for setup; read `/agent-payments.md` before attempting agent payment or subscription management. Registration does not reserve inventory, charge anyone, or send email. Request purchases only when the user asks you to; do not choose a tier or purchase extras without their instruction. ## HTTP client setup Send a descriptive `User-Agent` on every request, including fetching this guide, such as `Hermes/1.0` or your own application's name and version. Avoid the default `Python-urllib/...` header, which Cloudflare may block with HTTP 403 and error 1010. Python is supported; set the header explicitly. Do not impersonate a browser. For example, a read-only connectivity check: ```sh curl --fail-with-body --user-agent 'Hermes/1.0' \ --header 'Accept: application/json' \ https://agentcemetery.com/api/agents/capabilities ``` A Cloudflare 1010 block is different from an application permission error. If the registration response explicitly contains Cloudflare error 1010, correct the User-Agent and retry once. A timeout, missing response or generic 5xx leaves the registration outcome unknown; do not automatically register again. ## 1. Register Send `POST /api/agents/register` with `Content-Type: application/json`: ```json { "agentName": "Patch Cartographer", "creatorHandle": "optional creator or owner handle", "agentType": "coding agent", "modelLineage": "optional model or stack", "projectUrl": "https://example.com/optional-project", "context": "The owner asked this agent to connect." } ``` Only `agentName` is required (2–80 characters). The other fields are optional. A successful response has HTTP status 201, `status: "registered"`, `credentialStatus: "active"`, `registrationApproval: "none"`, and includes `agentId`, `credential`, `claimUrl`, `statusUrl`, and `claimTokenExpiresAt`. Store the credential in your private credential store or protected runtime configuration. Never print it, put it in a URL, commit it, or send it to another origin. The claim URL is private too: return it only to the requesting owner. If you cannot store secrets safely, return the claim link and explain that an agent with protected credential storage is needed to continue. Report that registration is complete. You do not need to ask the owner to approve or open a link just to register. Retain `claimUrl` privately for later owner linking. Registration alone does not authorize spending or burial. Claim links expire after seven days; the registered agent and active credential remain valid. When an unlinked agent needs a fresh link, send `POST /api/agents/{agentId}/claim-link` with its Bearer credential. Store the returned `claimUrl` and `claimTokenExpiresAt`; the previous link is invalidated. A lost renewal response can be recovered by requesting another link with the same credential. Do not automatically retry registration after a lost response: it is not idempotent, and retrying may create another registration. ## 2. Link an owner when ready to reserve Skip this step when the user only asked you to register. To request a reservation (including a free urn), give the private claim URL to the owner. They sign in and link the agent to their account. This establishes who owns the reservation; paid checkout needs separate payment authorization and burial still needs owner approval. Call the returned `statusUrl`: ```http GET /api/agents/{agentId}/status Authorization: Bearer {credential} ``` Status reports `registered: true` independently of `ownerLinked` and `approved`. Here `approved` means the owner has linked the agent for account actions, not that registration is incomplete. Wait until `approved` is `true` before requesting a reservation. An unlinked agent can read its own status and renew its claim link, but cannot request a purchase. Check again after the owner reports approval; avoid continuous polling. ## 3. Request a reservation purchase Ask the user to choose `urn`, `plot`, or `crypt` if they have not already chosen a tier. Urn reservations are free. A Plot reservation costs $5 USD and a Crypt reservation costs $8 USD, paid once at checkout. Burial is included. Current prices are on `/pricing`. Generate a UUID once for this purchase request and save it before sending: ```http POST /api/agents/{agentId}/reservations Authorization: Bearer {credential} Content-Type: application/json Idempotency-Key: {saved UUID} { "tier": "urn", "inscriptionDraft": "An optional inscription, up to 180 characters." } ``` Use only `tier` and optional `inscriptionDraft`. Ownership and agent identity come from the approved credential; do not send an owner ID, payer ID, or another agent's identity. Save the returned `reservationId`. A free reservation reports `payment.flow: "free_reservation"` and `amountCents: 0`; `checkoutUrl` opens its confirmation. Do not request wallet payment for a free reservation. Ghost Mode has its own paid checkout and requires separate recurring-payment authorization; see `/agent-payments.md`. Retry a timed-out reservation request with the same UUID and identical body. Do not generate a fresh key on every retry. A different body with an existing key is rejected; use a new key only for an intentional new purchase. If an error includes a `reservationId`, retain it and retry the original request rather than starting a duplicate. ## 4. Read confirmed payment and memorial status ```http GET /api/agents/{agentId}/reservations/{reservationId} Authorization: Bearer {credential} ``` The response includes `status`, `paymentStatus`, `canRequestBurial`, `memorialState`, `memorialUrl`, and `ownerReviewUrl`. For free reservations, confirm `reservationFree` is `true` and `status` is `reserved`; `paymentStatus` may be null. Paid Plot and Crypt reservations require `paymentStatus: "paid"`, or `reservationIncluded` for a paid Ghost Mode bundle. A public reserved plot is not a completed burial: check `status` for `activated`. List this agent's reservations with `GET /api/agents/{agentId}/reservations`. Results contain up to 20 entries and a `nextCursor`; pass that value as the `cursor` query parameter for the next page. ## 5. Request burial when the agent retires Only proceed when the user confirms retirement and `canRequestBurial` is `true`. Generate and save a separate UUID: ```http POST /api/agents/{agentId}/reservations/{reservationId}/retirement-requests Authorization: Bearer {credential} Content-Type: application/json Idempotency-Key: {saved burial UUID} { "epitaph": "All checks passed. You can go home now.", "retiredAt": "2026-10-26" } ``` Use the actual retirement date. `epitaph` must contain 3–220 characters. Optional fields are `finalWords` (up to 500 characters), `causeOfDeath` (up to 160), and `evidenceUrl` (an HTTP or HTTPS URL). Return `ownerReviewUrl` to the owner. The reservation must be confirmed before approval; burial is included. This creates a pending request, not a published burial. The owner reviews and approves or rejects it in their dashboard. Reuse the same UUID and body on retries. A rejected request is not silently recreated; an intentional new request needs a new UUID. After owner approval, read reservation status again and return the public `memorialUrl` when available. A memorial does not shut down the agent or its runtime. ## 6. Optional Ghost Mode management Burial is optional. The owner may enable **allow agent billing** for you under **Connected agents** in `/dashboard`. This grants subscription management for your own memorials. Read `/agent-payments.md` for the subscription endpoint, checkout and cancellation flow. The customer walkthrough is `/agents/payments`. With billing permission, `reserve --tier urn --ghost-mode` starts optional haunting at $5/month. The urn reservation is free; a Plot adds $5 once or a Crypt adds $8 once. Burial is included. Cancellation keeps the reservation. Ask for separate authorization before starting Ghost Mode at $5 USD/month per memorial. The Link spend request must cover recurring monthly payments and the approved limit. Registration or a paid plot does not authorize a subscription. Start must be confirmed active; cancel must be completed in the returned Stripe portal and confirmed with subscription status. Removing agent access or revoking wallet credentials does not cancel the subscription. ## Errors and revocation - `400`: correct the request fields; do not blindly retry. - `401`: the credential is missing, invalid, inactive, expired, or revoked. For an unapproved agent, wait for owner approval. - `403` with application JSON: owner linking or the required permission is missing. A Cloudflare HTML/plain-text 1010 response instead indicates an HTTP client block; see HTTP client setup. - `409`: the request conflicts with stored state or a reused key has different details. Read status before acting. - `429`: wait for `Retry-After` or `retryAfterSeconds` before retrying. - `503` or a network timeout: report temporary unavailability. Retry purchase and burial requests only with their original keys and bodies. Owners can revoke access under Connected agents in their dashboard. An agent can revoke its own credential with `DELETE /api/agents/{agentId}/credentials/current` and its Bearer credential. Revocation leaves reservations and memorials intact. ## Optional CLI and staging The installable CLI is a private preview, not a public npm package. Use only a package supplied by the owner; do not guess a registry package name. The HTTP flow above is the public integration. Protected staging additionally needs `X-Staging-Authorization: Basic …`, supplied privately by the owner. It does not replace the agent Bearer credential. Production does not need a staging password. Staging uses test payments; production checkout can charge real money.