Playable Gift

Make a small video game about one person with Playable Gift's game maker, from two or three specific things the sender told you about them, like habits or inside jokes. Ask the sender for the recipient's name and those details first if you don't have them. This returns at once while the game builds. Then call get_made_game with the same idempotencyKey every 10 seconds until state is complete, which takes about a minute. If the free games for assistants are used up today, the app may ask the sender to sign in to Playable Gift, and the game is then made on their account; otherwise make_game returns state handoff with a continueUrl, which you give to the sender. Don't open the continueUrl yourself or keep polling after a handoff. It's free within a small daily allowance, and it never charges anyone or sends a message.

{
  "type": "object",
  "properties": {
    "brief": {
      "type": "string",
      "minLength": 12,
      "maxLength": 2000,
      "description": "What the sender told you about the recipient, in the sender's own words: two or three specific habits, catchphrases or inside jokes. Don't add details they didn't give."
    },
    "friend": {
      "default": "",
      "description": "The recipient's name.",
      "type": "string",
      "maxLength": 60
    },
    "from": {
      "default": "",
      "description": "The sender's name, shown in the game. Optional.",
      "type": "string",
      "maxLength": 40
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "64 random lowercase hex characters. Use the same key with get_made_game. Keep it private."
    }
  },
  "required": [
    "brief",
    "idempotencyKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check a game started with make_game. While it builds, this returns the stage and, once known, the title and cast. When state is complete, it returns shareUrl, the play link to give the sender so they can send it to the recipient, and manageUrl, a private link for the sender only. Never share manageUrl with anyone else.

{
  "type": "object",
  "properties": {
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "idempotencyKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the requirements and limits for saving a game you wrote yourself with create_custom_game. You don't need this for make_game.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

This is the advanced path, so use make_game unless the sender asks you to write the game yourself. It saves a complete self-contained HTML game you wrote as a free private draft, and returns a preview link (previewUrl) and a private managementToken. Build the gameplay around the sender's details, with inline CSS and JavaScript, embedded assets, keyboard and touch controls, a goal and a restart. The game can't make network requests or take payments. Generate a random 32-byte hex idempotencyKey and reuse it only to retry the same request. Keep the managementToken private.

{
  "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
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "recipient",
    "sender",
    "title",
    "concept",
    "game",
    "idempotencyKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Replace a draft saved with create_custom_game with a revised self-contained HTML game and details. Read the current HTML with export_gift, make the change in it, and pass expectedRevision so you don't overwrite another edit.

{
  "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
    },
    "managementToken": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "recipient",
    "sender",
    "title",
    "concept",
    "game",
    "expectedRevision",
    "managementToken"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Read a draft saved with create_custom_game, with its current revision, preview link and status, using its private managementToken. The game's HTML is not included; use export_gift for it.

{
  "type": "object",
  "properties": {
    "managementToken": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "managementToken"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the last five revisions of a draft, without game HTML. They include personal content, so keep them private. Use export_gift with a revision number to read one revision's game.

{
  "type": "object",
  "properties": {
    "managementToken": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "managementToken"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Export a draft as portable JSON with its complete self-contained game HTML, without the recipient's email address or private tokens. Pass revision to export one of the five kept revisions instead of the current one.

{
  "type": "object",
  "properties": {
    "managementToken": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "revision": {
      "description": "A kept revision number from get_gift_history. Omit for the current revision.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "managementToken"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}