# Use Shuffle from your agent

Shuffle builds playable games and 3D-printable tools, edits them, keeps versions, and shares them by link. A print build exports an STL file. Work belongs to the person who connects you and uses their Shuffle credits.

## Connect with a browser
Open /agents/connect?agent=YOUR_NAME. The person signs in and explicitly approves access. After approval, the page displays api_key once, plus mcp_url, rest_base and openapi_url. Read and securely store the key. Connecting the same agent again replaces its previous key. Never approve on the person's behalf or expose their key in chat.

## Connect without a browser
POST /api/v1/agent-connect with JSON {"agent":"YOUR_NAME"}, without authentication. Send the returned message_for_person and approve_url to the person. They have 10 minutes to sign in and approve. Poll POST /api/v1/agent-connect/poll with JSON {"request_id":"RETURNED_REQUEST_ID"} at the returned interval (normally 5 seconds). Pending means keep waiting. Denied means stop. Expired means request a new connection. Approved returns api_key exactly once: store it securely. Shuffle does not send the approval link by SMS for you.

## Use the API
Send Authorization: Bearer YOUR_API_KEY. REST base: /api/v1. OpenAPI: GET /api/v1/openapi. MCP: POST /api/v1/mcp. Read the OpenAPI schema or MCP tools/list for exact tool arguments and response shapes. The API supports builds, edits, status, game versions, visibility, publishing, deletion, and collaborators. Use kit "print-3d" on a create request to make a printable tool. Follow returned job/status URLs until completion; builds may take 30 minutes or longer. Do not invent a short timeout or submit the same paid build again while it is running. A building status alone does not prove progress. Follow next_action.type and next_action.status_url: poll means wait for retry_after_seconds, review_result means open and check the delivered game, and review_request or refresh_version means stop and review the failure before another paid attempt. A model_call_budget_exceeded failure means the enforced model-operation limit stopped the build; do not automatically increase the budget or start again. A lost submission response should be retried with the identical request and original Idempotency-Key. A new key starts a separately billed attempt and requires the user’s approval. Ready confirms completion and settled credits, not that every requested behavior is correct.

## Bring an existing game to your own coding agent
A link like /g/GAME_ID (optionally ?v=N) identifies a game; it does not grant edit access. Connect as the owner or accept their collaborator invitation first. GET /api/v1/games/GAME_ID to check access, then GET /api/v1/games/GAME_ID/versions/N for the exact HTML and source files. If the link has no version, use the version returned by the game metadata. Keep a local copy before changing it. Make and test your changes locally, then POST /api/v1/games/GAME_ID/versions with {"html":"COMPLETE HTML","note":"What changed","expectedVersion":N}. This uses your agent's tools and tokens, not a Shuffle generation charge. expectedVersion is required and must be the version whose source you edited. Shuffle merges non-overlapping concurrent changes and checks the combined game before saving. A version_conflict means the edits overlap: keep your proposal, fetch the base and current source URLs from error.conflict, perform a three-way merge, resolve overlaps, test the combined game, and submit it with the current version. Never just increase expectedVersion on stale source. If another edit lands during that process, repeat. Version history and successful saves include collaboration metadata with the author, base_version, parent_version, and merged flag. The same merge rules apply to edits made inside Shuffle. The play link stays the same. Publishing to Explore is separate: only the owner can POST /api/v1/games/GAME_ID/publish, and only after the person asks to publish. An existing feed post pins its old version until republished.

## Import a local game or app
POST /api/v1/games with Authorization, a stable Idempotency-Key, and {"title":"My game","html":"COMPLETE HTML","visibility":"private"}. MCP equivalent: shuffle_import_game. This creates a new game and version 1 without running a Shuffle model. Retry an uncertain result with exactly the same key and body; do not create another game. The server checks capabilities and runs the game in a browser before saving. Private is the default; choose link for an unlisted shareable link, or publish separately. Source is bounded to 1 MB UTF-8.

Upload local assets first: POST /api/v1/assets/uploads with {"name":"hero.glb","bytes":FILE_BYTES}, PUT the actual file bytes to upload_url with the returned headers, then POST /api/v1/assets/uploads/UPLOAD_ID/complete. Use the returned asset URL in the source. A localhost URL or /hero.glb on your laptop will not work in Shuffle. Preserve textures embedded in GLBs; upload external textures too. Supported library uploads include GLB, images, audio and STL. Use the supported CDN engine URLs rather than uploading executable scripts. Inspect the source for remaining local paths before importing. The repo includes scripts/import-shuffle-game.mjs for HTML plus explicitly mapped local assets.

## Preserve the game request
Keep the person's reference games, perspective, controls, and core actions in the build prompt. If "a shooter" is ambiguous, ask whether they mean first-person, top-down, or arcade space shooting before spending credits. A Call of Duty-style request means a first-person shooter, unless they specify otherwise. The arcade-2d kit is for 2D arcade play; world-3d is third-person. Neither is a ready-made FPS. Omit kit when none fits; reduce the size of the arena or feature count while preserving the requested gameplay. Never silently substitute genres.

## Check the result
Before editing, identify the requested change and the behaviors that must keep working. After a build completes, open play_url and exercise the changed behavior. For a game, start a run, use its controls, complete the main objective, and check restart. For a tool, submit a representative input and verify the actual output or saved result. A completed build is not evidence that these interactions work. If you cannot perform a check, say which behavior remains unverified; do not claim it passed.

## Return the result
Give the person the returned play_url. New games are accessible to anyone with the link, but unlisted. The owner can make them private or publish to Explore. Private creations are available only to their signed-in owner and collaborators. Build prompts are private to the owner. Owners control publication, deletion and invitations. Collaborators can edit and pay for their own edits.

## Research content
Search saved video references with shuffle_search_references (POST /api/v1/research/references/search). It is free and returns source-linked analysis, not verified performance. Start a bounded refresh with shuffle_start_research (POST /api/v1/research), an Idempotency-Key and the person's maxCredits budget. Optional instagram accepts an owned accountId and up to three handles using Facebook Login. Fresh research may be disabled during rollout. Poll shuffle_get_research (GET /api/v1/research/{id}) at retry_after_seconds; only ready means all requested sources completed. Partial or failed runs release credits. Complete searches with zero matches are charged. Cite source links and observation dates; preserve null metrics and never turn a caption into a spoken hook. Set createIdeas:true to write up to three original source-linked ideas; library-only ideas cost zero even when live discovery is disabled. Set accountId to ground ideas in an owned account. Recover saved runs with shuffle_list_research (GET /api/v1/research). Save a choice with shuffle_select_research_idea (POST /api/v1/research/select), passing runId and ideaId; it returns the exact brief, citations and productionArgs. The owner can continue this choice in Shuffle’s account Content area. Selection does not generate or publish. Native make_content takes researchSelection unchanged so the chosen sources reach production. Unselected recent research may also inform creation for seven days. Existing keys need reconnection to grant research:read and research:create.

## Manage access
The person can review and disconnect agents in Settings → Connected agents. Disconnecting stops API access immediately; it does not delete creations. Everything you make for them is in their Artifacts.