Practice Pickleball

npx add-mcp 'https://practicepickleball.app/mcp'

Practice Pickleball API

Give players a ready-to-use practice session or help them find a drill. The API uses the same catalog, generator and session-building approach as this website.

Download the OpenAPI 3.1 specification. No API key is required. Use the REST endpoints below or the stateless MCP endpoint at https://practicepickleball.app/mcp for compatible AI tools. Both call the same services.

Automated discovery is available through the API catalog, with links to this documentation and the specification. The API has two operations described below.

Adding a planner or session preview to a club website or article? Use the free embed configurator and integration instructions for interactive, HTML, and responsive image exports.

MCP for AI tools

Connect a server-side MCP client using Streamable HTTP at /mcp. Tool discovery exposes generate_practice_session and find_drills, with input and output schemas. Their arguments follow the settings documented below; MCP search takes focus_skills as an array of IDs rather than a comma-separated query string.

Clients that support MCP prompts can discover two conversation starters: plan_practice (plan a session) and explore_drills (find drills). Both take no arguments and guide the assistant to use your existing preferences, ask for relevant missing details, and call the tools above. Retrieving a prompt returns text; it does not run a tool or generate a session. Prompt availability and presentation depend on your client.

Successful tool results contain the same data as REST in structuredContent, with a JSON text fallback. Domain failures are tool results with isError: true; protocol errors use JSON-RPC errors. HTTP safety limits can return 4xx or 503 before tool execution. The endpoint stores no client sessions and needs no login. Connecting or enabling it in an AI application is a separate, explicit step; it is not automatically available in every assistant.

Generate a practice session

POST https://practicepickleball.app/api/v1/sessions/generate with Content-Type: application/json:

{
  "skill_level": 3.5,
  "number_of_players": 2,
  "duration_minutes": 60,
  "focus_skills": [
    "third-shot-drop",
    "reset"
  ],
  "seed": 42
}

The response includes the session title, choices, resolved themes, ordered blocks, exact timings, player roles, setup, instructions and canonical drill links. Scoring rules, when present, are part of the instructions. The returned session_url opens that plan on the website.

• Levels: 2.5, 3.0, 3.5, 4.0, 4.5 or 5 (the site's 5.0+ option).
• One player: 30, 45, 60, 90 or 120 minutes; also supply solo_environment: court, wall or court-wall. Wall includes rebounders.
• Two or four players: 30, 45, 60, 90 or 120 minutes. Omit solo_environment.
• Focus: at most one theme for 30 minutes, two for 45 or 60, three for 90 or 120. Omit focus_skills or use an empty array for an automatically chosen focus.
• Omit seed for variety, or supply an integer from 0 to 4294967295 for reproducibility. The response includes the seed and catalog/generator versions.

Arbitrary durations are not supported. Neither are free-text notes, weaknesses, intensity preferences or equipment restrictions. Unsupported choices receive an error, not an approximate or silently relaxed plan.

Prepare → Build → Add Pressure → Play describes the progression. Group core blocks develop skills and add pressure; the closing block is a game. Solo finishers combine pressure and a measurable challenge. Changeovers, water and pack-up are labeled support, not drills. These labels describe block positions, not a promise that every later drill is physically harder.

Find drills

GET https://practicepickleball.app/api/v1/drills?skill_level=3.5&number_of_players=2&focus_skills=reset&limit=5

Optional filters: q (text search), skill_level, number_of_players, focus_skills (comma-separated IDs), solo_environment and format (timed, reps, live-game or overlay). Filters combine with AND. Solo environment matches the library's exact court, wall or anywhere category and requires one player.

Results contain total, offset, limit, has_more and a drills array. Use offset to paginate, with a maximum of 20 results per request. An empty result is valid.

Focus IDs

serve

Serve

return

Return

third-shot-drop

Third-shot drop

third-shot-drive

Third-shot drive

fourth-shot

Fourth shot

footwork

Footwork

dink

Dink

reset

Reset

fast-hands

Fast hands

transition

Transition

anticipation

Anticipation

lob

Lob

overhead

Overhead

speed-up

Speed-up

counter

Counter

volley

Volley

shape

Shape

out-balls

Out balls

communication

Communication

targeting

Targeting

Errors and limits

Errors contain error.code, message, field-level issues, suggestions and a request_id. Invalid settings or an infeasible session return 422. Malformed JSON returns 400; wrong methods return 405; oversized bodies return 413. A temporary service failure returns 503.

Bodies are limited to 8 KiB, query strings to 2048 characters, and body delivery to 10 seconds. Generation allows approximately 10 requests per IP per minute; search allows 60. Limits are enforced per Cloudflare location and are not exact global quotas. A 429 response includes Retry-After: 60. Shared networks and AI-tool egress addresses share these limits.

REST and MCP share the generation and search quotas. MCP additionally allows approximately 60 total requests per IP per minute for discovery, notifications and calls. Its entire JSON-RPC envelope must fit the same 8 KiB body limit. Send one message per POST; batching, persistent sessions and standalone event subscriptions are not supported.

Cross-origin browser access is disabled. CORS is not authentication: server-side clients can access the public API. No request bodies or search queries are deliberately included in application logs; Cloudflare still processes requests and IP addresses for delivery and abuse prevention. See Privacy and Terms of Use. Keep sensitive information out of requests.

Sessions are not saved to a database. Shared links replay the existing generator and may need updating when the catalog or generator changes. Link players back to the returned public URLs for the full courtside experience.