# info.description
Live Clash Royale meta, deck, and player-analysis data for AI agents. All endpoints except /api/gpt/markdown/{path} require an x-api-key header — see /auth.md. Paid per-call MCP tools live separately at https://mcp.trophycoach.com/api/mcp (x402/USDC).

Versioning: date-based (current: 2026-08-24, echoed in the API-Version response header). Breaking changes ship as a new version with at least 90 days of overlap, announced via Deprecation and Sunset headers (RFC 8594) on the retiring version and in /auth.md. Additive changes (new fields, new endpoints) are not versioned.

Errors: every non-2xx response is application/json with the Error envelope ({ error: { code, message, docs, details? } }). Rate limits: 300 requests per 60s per API key, reported via X-RateLimit-* headers; 429 responses include Retry-After.

# components.securitySchemes.apiKey.description
Static API key. See /auth.md for how to request access.

# components.headers.API-Version.description
The API version that produced this response (date-based).

# components.headers.X-RateLimit-Limit.description
Requests allowed per window for this API key.

# components.headers.X-RateLimit-Remaining.description
Requests remaining in the current window.

# components.headers.X-RateLimit-Reset.description
Unix epoch seconds when the current window resets.

# components.headers.Retry-After.description
Seconds to wait before retrying (429 only).

# components.schemas.Error.description
Typed error envelope returned by every non-2xx response.

# components.schemas.Error.properties.error.properties.details.description
Optional machine-readable context (e.g. validation issues).

# paths./api/gpt/meta.get.summary
Current meta snapshot for a trophy level or range

# paths./api/gpt/meta.get.parameters[].description
Player trophy count; resolved to a trophy range server-side

# paths./api/gpt/meta.get.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/player-analysis.post.summary
AI analysis of a player from their recent ladder battles

# paths./api/gpt/player-analysis.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/counter.post.summary
Best counters to a card or win condition, from real ladder data

# paths./api/gpt/counter.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/matchup.post.summary
Head-to-head win rate between two decks from ladder battles

# paths./api/gpt/matchup.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/deck-check.post.summary
Validate a deck and return quick structural feedback

# paths./api/gpt/deck-check.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/deck-doctor.post.summary
AI deck analysis: grade, synergy, meta fit, swaps, game plan

# paths./api/gpt/deck-doctor.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/evolution-tier.get.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/peer-percentile.get.summary
Percentile standing of a player vs peers at their trophy range

# paths./api/gpt/peer-percentile.get.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/royale-iq.get.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/upgrade-advice.post.summary
Ranked card-upgrade recommendations by projected win-rate gain

# paths./api/gpt/upgrade-advice.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/post-match.post.summary
Coaching notes for a player’s most recent battles

# paths./api/gpt/post-match.post.responses.401.description
Invalid or missing x-api-key (code: unauthorized)

# paths./api/gpt/markdown/{path}.get.summary
Markdown representation of public pages (unauthenticated)

# paths./api/gpt/markdown/{path}.get.parameters[].description
Page path, e.g. "guides/clash-royale-meta-movers". Empty for homepage.