# Foilwick: MTG Deck Builder, Playtester & Agent API

> Foilwick is a premium Magic: the Gathering deck builder, collection tracker and 3D playtesting bench. Players can also connect their own AI agent to read and edit their decks and collection through a single authenticated HTTP endpoint.

## Pages

- [Home / Landing](https://foilwick.com/welcome): What Foilwick is, and sign-up.
- [Deck builder](https://foilwick.com/builder): Build decks, tag cards by role, analyse curve, colours, legality and price.
- [Card search](https://foilwick.com/cards): Search the full card catalog by name, colour identity, type and format legality.
- [Collection](https://foilwick.com/collection): Track the cards you own, see collection value and which decks you can build.
- [Community decks](https://foilwick.com/decks): Public decks shared by other players.
- [3D playtest](https://foilwick.com/playtest): Solo goldfish playtesting with real card physics, replays and saved games.
- [Commander playtest](https://foilwick.com/commander-playtest) · [Deck tester](https://foilwick.com/mtg-deck-tester) · [Goldfish practice](https://foilwick.com/goldfish-mtg)
- [Connect agents](https://foilwick.com/agent-access): How to point an AI agent at Foilwick.
- [Membership](https://foilwick.com/membership) · [FAQ](https://foilwick.com/faq) · [Terms](https://foilwick.com/terms) · [Privacy](https://foilwick.com/privacy)

## Agent API

Endpoint: `POST https://foilwick.com/api/apps/<app id>/functions/agentGateway`

- Auth: `Authorization: Bearer fw_live_…` — a personal key the player creates under Profile → Connect agents. Every action is scoped to that key's owner.
- Body: JSON with an `action` field, e.g. `{"action":"list_decks"}`.
- Rate limit: 60 requests per minute per key.
- Discovery: `{"action":"describe"}` returns the full, always-current action catalog with parameters — no key required. Call it first rather than relying on this file.
- Keys are read-only or read + write; write actions are rejected on a read-only key.

### Read actions

`me`, `list_decks`, `get_deck`, `search_decks`, `get_deck_share`, `analyze_deck`, `missing_cards`, `search_cards`, `get_card`, `card_rulings`, `random_card`, `price_check`, `buy_list`, `list_collection`, `collection_value`, `list_tags`.

### Write actions

`create_deck`, `add_cards`, `remove_cards`, `move_cards`, `set_commander`, `rename_deck`, `clone_deck`, `delete_deck` (requires a second call with `confirm: true`), `set_deck_visibility`, `import_decklist`, `import_from_url`, `create_tag`, `tag_cards`, `update_collection`.

### Notes for agents

- Call `me` first to orient yourself: the player's name, decks, collection size and tag vocabulary.
- Colour filters use colour identity (cost plus rules text), not casting cost.
- Role tags are account-wide, so any tag can be applied to a card in any of the player's decks.
- Never send `confirm: true` to `delete_deck` on the first attempt — confirm the exact deck with the player first.