{"openapi":"3.1.0","info":{"title":"GameMaster Personal Setup API","version":"1.0.0","description":"Connect at /play/agents. Scoped user settings only; no gameplay, payments, or administrator operations."},"servers":[{"url":"/"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"User-created expiring key from /play/agents. Never put keys in URLs."}}},"security":[{"agentKey":[]}],"paths":{"/api/gm/agent/catalog":{"get":{"operationId":"getSetupCatalog","security":[],"responses":{"200":{"description":"Setup catalog, current values, preview, or saved settings.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/gm/agent/setup":{"get":{"operationId":"getMySetup","description":"Requires setup:read. Returns only this player and owned rooms, allowed fields and revisions.","responses":{"200":{"description":"Setup catalog, current values, preview, or saved settings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"413":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"415":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"patch":{"operationId":"updateMySetup","description":"Requires setup:write. Applies one target atomically with stale revision protection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"target":{"type":"string","const":"player"},"expectedRevision":{"type":"string","minLength":64,"maxLength":64},"changes":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":80},"adaptivePersonalizationEnabled":{"type":"boolean"},"retainEngagementEvidenceExcerpts":{"type":"boolean"},"engagementObservationRetentionDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false}},"required":["target","expectedRevision","changes"],"additionalProperties":false},{"type":"object","properties":{"target":{"type":"string","const":"room"},"roomId":{"type":"string","maxLength":16,"pattern":"^\\d+$"},"expectedRevision":{"type":"string","minLength":64,"maxLength":64},"changes":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"languagePreference":{"type":"string","enum":["auto","en","es","fr","de","it","nl","ja","pt","pl","uk","ru"]},"sourceMode":{"type":"string","enum":["canon","remix"]},"adventureTone":{"type":"string","maxLength":240},"adventureLength":{"type":"string","enum":["one-shot","short-campaign","campaign"]},"adventurePlayerWishes":{"type":"string","maxLength":2000},"adventureBoundaries":{"type":"string","maxLength":2000},"voiceRuntimeMode":{"type":"string","enum":["auto","realtime_fast","mapped_cascade"]}},"additionalProperties":false}},"required":["target","roomId","expectedRevision","changes"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Setup catalog, current values, preview, or saved settings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"413":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"415":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/gm/agent/preview":{"post":{"operationId":"previewMySetup","description":"Requires setup:read. Validates ownership, revision and changes without saving.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"target":{"type":"string","const":"player"},"expectedRevision":{"type":"string","minLength":64,"maxLength":64},"changes":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":80},"adaptivePersonalizationEnabled":{"type":"boolean"},"retainEngagementEvidenceExcerpts":{"type":"boolean"},"engagementObservationRetentionDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false}},"required":["target","expectedRevision","changes"],"additionalProperties":false},{"type":"object","properties":{"target":{"type":"string","const":"room"},"roomId":{"type":"string","maxLength":16,"pattern":"^\\d+$"},"expectedRevision":{"type":"string","minLength":64,"maxLength":64},"changes":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"languagePreference":{"type":"string","enum":["auto","en","es","fr","de","it","nl","ja","pt","pl","uk","ru"]},"sourceMode":{"type":"string","enum":["canon","remix"]},"adventureTone":{"type":"string","maxLength":240},"adventureLength":{"type":"string","enum":["one-shot","short-campaign","campaign"]},"adventurePlayerWishes":{"type":"string","maxLength":2000},"adventureBoundaries":{"type":"string","maxLength":2000},"voiceRuntimeMode":{"type":"string","enum":["auto","realtime_fast","mapped_cascade"]}},"additionalProperties":false}},"required":["target","roomId","expectedRevision","changes"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Setup catalog, current values, preview, or saved settings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"413":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"415":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Request rejected. Read error/message; 409 requires a fresh revision, 429 requires backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}