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

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

## Manage access
The person can review and disconnect agents in Settings → Connected agents. Disconnecting stops API access immediately; it does not delete creations. All creations are available in the Creations tab.