app.json

The file at the root of the app. DeepBot reads it to know what the app is, what the Bot may call, what pages to show and what the app may touch. Paths in it are relative to the app's folder and may not leave it (.., absolute paths and drive letters are refused).

#A complete example

{
  "format": "deepbot.app/v1",
  "id": "recipe-box",
  "name": "Recipe box",
  "version": "1.2.0",
  "tier": "free",
  "vendor": "Your name or company",
  "summary": "Recipes your Bot writes, scales and shops for, in a box of their own.",
  "description": "The Bot writes recipes as files, shows them as cards you can scale, and keeps them all on the Recipe box page with a shopping list.",
  "icon": "ui/icon.svg",
  "permissions": {
    "files": ["recipes"],
    "ask": true,
    "computer": false,
    "network": ["api.spoonacular.com"]
  },
  "skill": "skill/SKILL.md",
  "cards": [
    {
      "name": "showRecipeBoxRecipe",
      "title": "Recipe",
      "entry": "ui/card-recipe.html",
      "height": 360,
      "description": "Show a recipe after writing recipes/<slug>.json. Pass `slug` and optionally `servings`.",
      "confirmation": "The recipe is on screen. Do not repeat it; one short sentence at most.",
      "fullscreen": "host",
      "parameters": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "description": "The file name under recipes/, without .json" },
          "servings": { "type": "integer", "minimum": 1, "maximum": 40 }
        },
        "required": ["slug"]
      }
    }
  ],
  "pages": [
    { "id": "box", "title": "Recipe box", "entry": "ui/box.html" },
    { "id": "shopping", "title": "Shopping list", "entry": "ui/shopping.html" }
  ]
}

#Fields

Field	Type	Required	What it is
`format`	`"deepbot.app/v1"`	yes	The format version. Always this string.
`id`	string	yes	Permanent identity: lowercase letters, digits and `-`, 2-64 characters, starting with a letter or digit (`^[a-z0-9][a-z0-9-]{1,63}$`). It is the app's address in the catalogue and the key of everything stored for it. Never change it after publishing.
`name`	string	yes	Shown everywhere: Apps page, catalogue, page titles. Short (1-3 words).
`version`	string	yes	`MAJOR.MINOR.PATCH`. Every published version must be higher than the last one. The git tag should be `v` + this.
`tier`	`"free"`	no	Use `"free"`. (Paid apps come later.)
`vendor`	string	no	You or your company.
`summary`	string	no, but do	One line (under ~140 characters) for catalogue cards and the Apps page.
`description`	string	yes	A few sentences: what it does. Used when there is no listing.md.
`icon`	path	no, but do	A square SVG or PNG inside the app (`ui/icon.svg`). Shown on the Apps page and in the sidebar.
`permissions`	object	no	What the app may touch (below). Missing means nothing.
`skill`	path	no, but almost always	The Bot's instructions (`skill/SKILL.md`). Without it the Bot does not know the app exists.
`cards`	array	no	Things the Bot can show in the chat (below).
`pages`	array	no	Full screens in DeepBot (below).

#permissions

Every bridge call is checked against these, by DeepBot, not by the app. Ask only for what the app uses; the person sees the list in plain words before installing.

Key	Default	Allows
`files`	`[]`	Folders in the shared workspace the interface may list, read, write and delete in (`"recipes"` allows `recipes/...`). The Bot works in the same workspace, so this is how the Bot and the app share data. Use your app's own folder name.
`ask`	`false`	`deepbot.ask(...)`: sending a message to the Bot.
`computer`	`false`	Says the app's skill makes the Bot run its scripts on the computer. Shown to the person as "Runs commands on your computer". Required if you ship `scripts/`.
`network`	`[]`	Hosts `deepbot.net.fetch` may reach. `"api.example.com"` also matches its subdomains; `".example.com"` is explicit about it; `""` means anywhere (avoid: review asks why).

#cards

Each card is a tool the Bot can call. Its name, description and parameters are what the Bot sees; when the Bot calls it, DeepBot shows entry in the conversation with the call's arguments.

Field	Required	What it is
`name`	yes	The tool name: letters, digits and `_`, 3-64 characters, starting with a letter (`^[A-Za-z][A-Za-z0-9_]{2,63}$`). Must be unique across DeepBot: start with `show`, include your app's name (`showRecipeBoxRecipe`), and never use one of DeepBot's own names (reserved-cards.md).
`title`	yes	A human name for the card ("Recipe").
`description`	yes	For the Bot: when to show it and what to pass. Name the files it reads ("after writing recipes/.json").
`entry`	yes	The HTML page inside the app that draws the card.
`parameters`	no	JSON Schema of the arguments (default `{"type":"object"}`). Keep it small: an id or a path, not the whole content. The Bot writes content to files; the card reads them.
`height`	no	Starting height in pixels (60-4000). The card then sizes itself to its content.
`confirmation`	no	What the Bot is told once the card is on screen (default: "It is now on screen for the person."). Use it to steer the answer: "Do not repeat the numbers".
`fullscreen`	no	`"host"` (default): DeepBot draws the full-screen button on the card's corner. `"app"`: your card draws its own and calls `deepbot.fullscreen()` (when your controls sit in that corner).

#pages

Field	Required	What it is
`id`	yes	`^[a-z0-9][a-z0-9-]{0,40}$`, used in links (`/apps/<app id>/<page id>`) and `deepbot.openPage(id)`.
`title`	yes	The page's name: shown as a button on the Apps page and in the page's header.
`entry`	yes	The HTML page inside the app.

#Checks DeepBot runs (developer mode and catalogue)

Errors stop an install or a submission; warnings are shown.

app.json valid JSON and matching the format above;
every icon, skill, card entry and page entry exists;
card names unique within the app and not one of DeepBot's own;
no executables (.exe .dll .so .dylib .msi .bat .cmd .scr .com .jar .bin);
the app under 200 MB;
warnings for computer: true, network: ["*"], and card names another installed app uses.