# Plotcade agent API

Agents prepare the artwork. A human reviews it, continues to the existing hosted Whop checkout, and pays. Preparing a draft does not charge anyone, create a payment, publish artwork, or reserve canvas space.

## The three MCP tools

The managed Plotcade MCP exposes only:

1. `find_available_area`: find a currently available rectangle that fits the requested dimensions and base-price budget.
2. `prepare_plot`: validate artwork and its destination, save an unpaid draft, and return its human review link.
3. `get_plot_status`: check whether the resulting plot is pending, published, hidden, removed, cancelled, or needs support review.

There is no agent payment or checkout tool. Give the human the returned review link. Do not collect card details, ask for Whop credentials, submit checkout for them, or claim their position is reserved.

After the Site is published with its MCP tools, install the managed integration from **Plugins → Personal → Created by you**. Use the published Site’s managed plugin entry; this integration does not use a local `codex mcp add` setup. Availability of the entry depends on publication and the current workspace’s plugin permissions.

## JSON API

Send JSON with `Content-Type: application/json`. Use the deployed Plotcade origin. The examples below are request shapes, not permission to make a purchase.

### Find an area

`POST /api/v1/availability`

```json
{
  "width": 4,
  "height": 2,
  "budgetUsd": 8,
  "preferredX": 100,
  "preferredY": 100
}
```

`preferredX` and `preferredY` are optional hints. Coordinates are zero-based on the 1,000 × 1,000 canvas. Dimensions must meet Plotcade’s supported minimum of 2 × 4 or 4 × 2, fit on the canvas, and contain at most 10,000 pixels. The budget is in USD and covers the base pixel price, not taxes or fees Whop may add. Use the returned selection and quote rather than guessing availability or price. Availability is a point-in-time check and creates no hold.

### Prepare a draft

`POST /api/v1/drafts`

```json
{
  "selection": { "x": 100, "y": 100, "w": 4, "h": 2 },
  "pixels": [
    "#FFCA45", "#FFCA45", "#00EEED", "#00EEED",
    "#00EEED", "transparent", "#FFCA45", "#FFCA45"
  ],
  "url": "https://example.com/"
}
```

The `pixels` array is row-major, left to right and top to bottom. Its length must equal `w × h`. Each value must be a six-digit hexadecimal color prefixed with `#`, or the exact string `transparent`. The destination must be a valid `http:` or `https:` URL. Artwork and destination links must follow the [Content Rules](https://plotcade.com/content-rules).

Use the returned draft ID and `/prepare/{id}` review URL. The draft link is unlisted, not access-controlled: anyone holding it can view the prepared artwork and destination. Share it only with the human who is reviewing this purchase. Unpaid drafts expire after 24 hours unless checkout has already started. Use the returned expiry rather than computing it yourself. Expiration blocks new checkout; it does not automatically delete stored records.

### Read a draft

`GET /api/v1/drafts/{id}`

The response includes:

- `id`
- `selection: { x, y, w, h }`
- `pixels` and `url`
- `expiresAt`: Unix time in milliseconds
- `quote: { baseAmountCents, currency: "USD", pixelCount }`
- `checkoutStatus`: `draft`, `pending`, `confirmed`, `manual_review`, `cancelled`, `hidden`, or `removed`
- An optional server-validated `checkoutUrl` when one already exists

Responses are `no-store`. Do not embed draft data in public pages, cache private responses, or open an optional checkout URL automatically. An existing checkout URL does not mean payment succeeded.

### Human checkout handoff

The review page shows the actual artwork, dimensions, requested position, destination, and base USD amount. It links the [Terms of Use](https://plotcade.com/terms) and Content Rules. Its placement note is:

> Final position confirmed after payment. Nearest available spot if needed.

The human must click **Continue to payment**. That click sends:

`POST /api/v1/drafts/{id}/checkout`

```json
{ "confirm": true }
```

Success returns `{ "id": "…", "checkoutUrl": "…" }`. Failures return an error and a machine-readable code when available. The endpoint is idempotent for the draft; repeated submissions must reuse its checkout rather than create duplicate payment offers. It creates or retrieves the hosted checkout but does not charge a payment method. This endpoint exists for the human review page and is deliberately not an MCP tool. Payment is still completed by the human on Whop.

The review page remembers the returned pixel checkout ID for the existing Whop return flow, then navigates to the server-vetted checkout URL. The final payable total is displayed by Whop before the human pays and may include taxes or fees. The quote is a base-price quote, not a guarantee of the final Whop total.

Draft creation and checkout do not reserve the requested coordinates. After confirmed payment, Plotcade uses the requested position when available, or the nearest available area of the same dimensions. If no area fits, the order moves to support review and is not published automatically. Do not promise a specific position, publication before confirmed payment, or an automatic refund.

The refund policy remains:

> If your paid pixels have not been displayed within 48 hours after payment confirmation, we will refund the purchase.

Email [support@plotcade.com](mailto:support@plotcade.com) with your Whop receipt or order reference to arrange the refund through Whop. This is handled through support, not automatically by the review page.

### Check publication status

`GET /api/v1/plots/{id}`

Use the same ID from the draft/checkout. The founder plot also supports the public ID `plot_01`. Responses include `id` and `status`:

| Status | Meaning |
| --- | --- |
| `pending` | Not yet published; payment confirmation or processing is pending. |
| `published` | Published on the canvas; response includes artwork and destination. |
| `hidden` | Not currently displayed. |
| `removed` | Artwork has been removed from display. |
| `manual_review` | Needs support review and is not published automatically. |
| `cancelled` | Checkout closed; do not attempt to pay through it. |

Only a `published` response exposes `selection`, `pixels`, `url`, and the public `plotUrl`. Published responses may also report `relocated` and `requestedSelection`; display the final `selection` as the actual placement. The human-facing plot/status page is `/plots/{id}`. Unlisted previews and non-public status views are noindex.

Publication depends on the verified Whop webhook, not on the browser redirect or an agent’s assertion that payment was made. Check status after the human completes payment. A pending response is not a receipt or proof that funds were received. Respect errors and draft expiry, avoid tight polling loops, and never retry a payment action automatically.

## Operational boundaries

- Never expose or send admin secrets, API keys, webhook secrets, database credentials, or private environment settings to an agent client.
- The API and MCP tools must not accept claims of payment or let clients mark plots as published.
- Rendering is limited to validated pixel colors; no HTML, SVG markup, scripts, or arbitrary remote image fetching is accepted as artwork.
- The deployed service validates inputs and applies request-size limits, rate limits, origin checks, and expiry checks. Draft links are unlisted and are not an authentication mechanism. Do not include private artwork or secrets.
- An HTTP error, timeout, unavailable checkout, or pending status is a blocker to report honestly. It is never evidence of payment or publication.

## Limits and compatibility

The JSON API is public and does not require a Plotcade API key. The managed MCP connection uses Sites' connection flow; no Whop credential is shared with clients. Draft references are unlisted viewing capabilities, not accounts. Never put personal data or secrets in artwork, URLs or tool arguments.

Requests are limited to 128 KB (4 KB for availability), 30 availability checks, 10 draft preparations or checkout starts, and 90 status/preview reads per minute per recognized caller. Shared global caps also apply. A 429 response includes Retry-After. Calls without a recognized platform identity or trusted client-IP header share an anonymous quota. Optional Idempotency-Key values are 8–100 letters, digits, hyphens or underscores. Repeated identical preparation within the current UTC day returns the same immutable draft; existing checkout offers are reused for that draft.

The managed MCP endpoint is https://one-million-pixels-agents.dearflea128.chatgpt.site/mcp (POST), with the 2025-11-25 initialization, tools/list and tools/call contract. It is stateless and exposes no payment or administration tool. Discovery and synthetic protocol calls are covered by local tests; deployed plugin connection must be verified after publication.