{"openapi":"3.1.0","info":{"title":"Playable Gift Agent API","version":"0.2.0","description":"Create free private drafts, revise and export content, reserve named gift addresses, and prepare Stripe TEST checkout. Customer email, custom domains, credits and gift-card rewards are not implemented."},"servers":[{"url":"https://playablegift.com"}],"externalDocs":{"url":"https://playablegift.com/SKILL.md"},"components":{"securitySchemes":{"managementToken":{"type":"http","scheme":"bearer","description":"Private 64-character management token returned only when creating a gift. Keep it out of public content."}},"schemas":{"CreateGift":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"recipient":{"type":"string","minLength":1,"maxLength":60},"sender":{"type":"string","minLength":1,"maxLength":60},"title":{"type":"string","minLength":1,"maxLength":80},"concept":{"type":"string","minLength":1,"maxLength":2000},"occasion":{"default":"just-because","type":"string","enum":["birthday","anniversary","thank-you","just-because"]},"theme":{"default":"sunshine","type":"string","enum":["sunshine","midnight","rose"]},"message":{"default":"","type":"string","maxLength":2000},"recipientEmail":{"default":"","anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]},"game":{"type":"object","properties":{"html":{"type":"string","minLength":100,"maxLength":120000,"description":"Complete self-contained HTML video game, with inline CSS/JS and embedded assets. No external dependencies, fetches, forms, popups, payments or personal-data collection. Use canvas or DOM controls, keyboard/touch support, restart and clear win/lose states. Notify the parent of a win with parent.postMessage({type:'playablegift:complete'}, '*')."}},"required":["html"],"additionalProperties":false},"slug":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{1,38})[a-z0-9]$"},"idempotencyKey":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["recipient","sender","title","concept","game","idempotencyKey"],"additionalProperties":false},"ReviseGift":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"recipient":{"type":"string","minLength":1,"maxLength":60},"sender":{"type":"string","minLength":1,"maxLength":60},"title":{"type":"string","minLength":1,"maxLength":80},"concept":{"type":"string","minLength":1,"maxLength":2000},"occasion":{"default":"just-because","type":"string","enum":["birthday","anniversary","thank-you","just-because"]},"theme":{"default":"sunshine","type":"string","enum":["sunshine","midnight","rose"]},"message":{"default":"","type":"string","maxLength":2000},"recipientEmail":{"default":"","anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]},"game":{"type":"object","properties":{"html":{"type":"string","minLength":100,"maxLength":120000,"description":"Complete self-contained HTML video game, with inline CSS/JS and embedded assets. No external dependencies, fetches, forms, popups, payments or personal-data collection. Use canvas or DOM controls, keyboard/touch support, restart and clear win/lose states. Notify the parent of a win with parent.postMessage({type:'playablegift:complete'}, '*')."}},"required":["html"],"additionalProperties":false},"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["recipient","sender","title","concept","game","expectedRevision"],"additionalProperties":false}}},"paths":{"/api/agent/catalog":{"get":{"operationId":"get_gift_catalog","summary":"Read game requirements, pricing and integration availability","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/agent/names":{"get":{"operationId":"check_gift_name","summary":"Check name availability","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}},"parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":40}}]}},"/api/agent/games":{"post":{"operationId":"create_custom_game","summary":"Create or replay a free private draft","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGift"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/agent/gift":{"get":{"operationId":"get_gift","summary":"Read gift status and links","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","security":[{"managementToken":[]}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/agent/gift/revisions":{"get":{"operationId":"get_gift_history","summary":"Read the last five private revisions","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","security":[{"managementToken":[]}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}},"post":{"operationId":"revise_custom_game","summary":"Replace draft with optimistic revision check","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","security":[{"managementToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseGift"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/agent/gift/name":{"post":{"operationId":"reserve_gift_name","summary":"Reserve a named gift address","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","security":[{"managementToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{1,38})[a-z0-9]$"}},"required":["slug"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/agent/gift/export":{"get":{"operationId":"export_gift","summary":"Export portable gift JSON","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","security":[{"managementToken":[]}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}}}},"/api/manage/{managementToken}/{action}":{"post":{"operationId":"manage_test_checkout","summary":"Prepare test checkout, confirm payment or retry test delivery","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}},"parameters":[{"name":"managementToken","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["checkout","confirm","delivery"]}},{"name":"Origin","in":"header","required":true,"schema":{"type":"string","const":"https://playablegift.com"}}]}},"/api/preview/{previewToken}":{"get":{"operationId":"get_private_preview","summary":"Read-only private draft preview","description":"Read /SKILL.md for privacy, retries and exact sandbox restrictions.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing bearer token"},"404":{"description":"Gift not found"},"409":{"description":"Name/revision/checkout conflict"},"429":{"description":"Traffic or storage allowance reached; respect Retry-After"},"503":{"description":"Sandbox provider setup unavailable"}},"parameters":[{"name":"previewToken","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}]}}}}