Skip to content

Bot template format ​

A bot template is one JSON file that describes a bot people can import: its instructions, skills, routines and the services it works with. It never carries keys, secrets or chats, so it's safe to share in public. Files use the extension .casama-bot.json, and the format is called casama.bot, version 1.

Where templates come from ​

  • Export from the app. In a bot's settings, Share as template saves the file or copies a share link. You choose whether to include the bot's memories.
  • Export from the API. GET /v1/bots/{id}/export returns the template for any bot you can see. Add ?memories=true to include memories; that only takes effect for people who manage the bot.
  • Write one by hand. It's plain JSON; the full example below is a good start.
sh
curl -s "https://casama.example.com/v1/bots/$BOT/export" \
  -H "authorization: Bearer $TOKEN" > invoicer.casama-bot.json

A full example ​

json
{
  "format": "casama.bot",
  "version": 1,
  "name": "Invoicer",
  "description": "Chases unpaid invoices politely.",
  "persona_md": "You chase unpaid invoices for a small design studio. Be polite and brief...",
  "autonomy": "ask_risky",
  "avatar": "mascot:cool",
  "skills": [
    {
      "name": "dunning",
      "description": "Follow-up cadence for overdue invoices. Use when an invoice is past due.",
      "body_md": "1. Day 7: a friendly reminder.\n2. Day 14: a firmer note with the invoice attached.\n3. Day 30: tell me before sending anything else.",
      "files": [
        {
          "path": "templates/reminder.md",
          "content_base64": "SGkge25hbWV9LCBqdXN0IGEgcmVtaW5kZXIuLi4=",
          "executable": false
        },
        {
          "path": "scripts/overdue.sh",
          "content_base64": "IyEvYmluL2Jhc2gKZWNobyAiY2hlY2tpbmcuLi4iCg==",
          "executable": true
        }
      ]
    }
  ],
  "routines": [
    {
      "name": "Weekly chase",
      "instructions_md": "Check for overdue invoices and follow the dunning skill.",
      "schedule_cron": "0 9 * * 1"
    }
  ],
  "connections": [
    { "kind": "composio", "name": "gmail" },
    { "kind": "mcp", "name": "accounting" }
  ],
  "memories": [
    { "kind": "preference", "content": "Invoices go out from billing@example.com." }
  ]
}

Fields ​

FieldTypeRequiredRules
formatstringyesAlways "casama.bot"
versionintegeryesAlways 1
namestringyes1 to 80 characters
descriptionstringnoUp to 300 characters. A one-line summary for people browsing templates.
persona_mdstringyesThe bot's instructions, in Markdown. Up to 20,000 characters (can be empty).
autonomystringyesask_always, ask_risky or autonomous
avatarstring or nullnoA built-in mascot, mascot:<name>, or null
skillsarraynoUp to 30. See Skills.
routinesarraynoUp to 20. See Routines.
connectionsarraynoUp to 30. See Connections.
memoriesarraynoUp to 200. See Memories.

The optional lists can be left out; a missing list means none.

autonomy ​

How much the bot may do without asking. See Autonomy and approvals.

ValueMeaning
ask_alwaysAsks before any action with side effects
ask_riskyThe default. Asks before high-risk actions, paid data lookups and payments, and before a medium-risk action that sends data out after reading outside content
autonomousAsks only before high-risk actions on personal computers

avatar ​

One of the built-in mascots: mascot:cool, mascot:focused, mascot:giggly, mascot:lovey, mascot:shy, mascot:sleepy, mascot:starry, mascot:thinker, mascot:winky or mascot:wow. Anything that doesn't start with mascot: is dropped on import, and uploaded pictures are never exported.

Skills ​

The bot's own skills, in the open Agent Skills shape. See Skills.

FieldTypeRequiredRules
namestringyesLowercase letters, digits, - and _, starting with a letter or digit; up to 63 characters
descriptionstringyes1 to 300 characters. The bot reads it when choosing a skill, so say when to use it.
body_mdstringyesThe skill's instructions, up to 50,000 characters
filesarraynoFiles the skill uses, up to 60

Each file:

FieldTypeRequiredRules
pathstringyesA relative path of letters, digits, ., _, - and /, with no ..
content_base64stringyesThe file's bytes, base64-encoded. Up to 1 MB per file once decoded.
executablebooleannoKeep the executable bit (default false)

A skill's files can total up to 5 MB. Scripts in a skill only ever run on the bot's own sandboxed computer, never on the Casama server.

Routines ​

Repeating schedules. See Routines.

FieldTypeRequiredRules
namestringyes1 to 120 characters
instructions_mdstringyesWhat to do each time, 1 to 20,000 characters
schedule_cronstringyesA standard 5-field cron expression, such as 0 9 * * 1 (Mondays at 9:00)

There's no time zone in the file: routines run in the importing person's time zone. An end (ends_at or max_runs) doesn't travel either, so imported routines repeat until someone sets one.

An export includes every routine with a cron schedule, paused ones too, except check-ins, which belong to the bot's check-in settings. Imported routines start switched on.

Connections ​

Services the bot works with, so the person importing knows what to connect. Names only: no credentials, tokens or addresses ever travel.

FieldTypeRules
kindstringThe connection type, such as mcp, openapi, composio or a2a. Up to 40 characters.
namestringThe connection's name in the exporting workspace. Up to 120 characters.

Memories ​

Only present when the person exporting chose to include them.

FieldTypeRules
kindstringfact, episode, summary or preference
contentstring1 to 8,000 characters

An export includes up to 200 memories, pinned and most important first.

Never in a template ​

Casama never writes these into a template, and import doesn't read them:

  • model keys, secrets, OAuth tokens or any other credential
  • the model choice (the person importing picks a key and model)
  • chats and conversation history
  • files from the bot's computer
  • uploaded avatar pictures
  • skills shared by the whole workspace, turned-off skills, and routines that aren't on a repeating schedule (webhook, one-time and other triggers)

Import a template ​

In the app, open Bots → Import a bot and pick the file, or open a share link (https://<your app>/import/<token>). Casama previews the instructions, skills, routines, connections and memory count, and you choose a model key and model, and whether to bring the routines and memories.

From the API, POST /v1/bots/import:

sh
jq -n --slurpfile t invoicer.casama-bot.json \
  --arg org "$ORG" --arg key "$CREDENTIAL" --arg model "$MODEL" \
  '{org_id: $org, template: $t[0], credential_id: $key, model: $model,
    include_routines: true, include_memories: false}' |
curl -s -X POST "https://casama.example.com/v1/bots/import" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d @-
FieldRequiredMeaning
org_idyesThe workspace to create the bot in
templateyesThe template file's contents
credential_idyesA model key from that workspace
modelyesThe model id the bot uses on that key

On Casama Cloud, and on any server where billing and Casama's own model upstream are switched on, the new bot uses the server's cloud model and credits instead: credential_id and model are still required but replaced. | include_routines | no | Create the routines (default true) | | include_memories | no | Add the memories (default true) |

It answers 201 Created:

json
{
  "bot_id": "2a7d4c1e-9b8f-4e6a-8c5d-3f2e1a0b9c8d",
  "skills": 1,
  "routines": 1,
  "memories": 0,
  "connections_to_add": [
    { "kind": "composio", "name": "gmail" },
    { "kind": "mcp", "name": "accounting" }
  ]
}

What import does:

  • Checks first. The file must match the schema above (validation_failed lists what's wrong), every skill's files are checked against the limits, and every routine's cron schedule is validated. A problem stops the import with nothing created (skill_too_large, skill_bad_path or invalid_cron).
  • Creates a new bot owned by you, with the template's name, instructions, autonomy and mascot, and the key and model you picked. It counts toward your plan's bot limit when billing is on.
  • Adds the skills with their files and executable bits.
  • Adds the routines (if include_routines) in your profile's time zone, or UTC if you haven't set one.
  • Adds the memories (if include_memories).
  • Doesn't connect anything. connections_to_add lists the services to connect yourself; see Connections.

Importing always creates a new bot; it never changes an existing one. Common errors: forbidden (you can't create bots in that workspace), credential_not_found (the key isn't in that workspace) and the plan's bot limit.

Convert an agent from OpenClaw or Hermes Agent ​

POST /v1/agent-imports reads an OpenClaw or Hermes Agent folder and returns a casama.bot template for you to review. Nothing is created yet. Send the folder as a ZIP or as a list of files, up to 50 MB and 3,000 files:

sh
jq -n --arg org "$ORG" --arg zip "$(base64 < openclaw.zip | tr -d '\n')" \
  '{org_id: $org, zip_base64: $zip}' |
curl -s -X POST "https://casama.example.com/v1/agent-imports" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d @-
Response fieldMeaning
idThe import, for copying the leftover files later
kindopenclaw or hermes
templateA casama.bot template, ready for POST /v1/bots/import
sourcesWhere each skill, routine and memory came from, in the same order as the template
leftoversFiles nothing mapped to, with their size
skippedFiles that were never read (keys, settings, sessions, logs), with the reason
notesWhat was left out or trimmed, such as paused jobs or a persona over 20,000 characters

Drop what you don't want from template, then send it to POST /v1/bots/import as above. To copy the leftovers to ~/imported/openclaw/ or ~/imported/hermes/ on the new bot's computer, call POST /v1/agent-imports/{id}/files with {"bot_id": "..."} (for people who manage the bot). It answers 409 while the bot has no computer yet. Uploads are kept for a day. See Import an agent for what each kind maps to.

POST /v1/bots/{id}/share (for people who manage the bot) saves a snapshot of the template and returns a link:

sh
curl -s -X POST "https://casama.example.com/v1/bots/$BOT/share" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"include_memories": false, "expires_in_days": 30}'
json
{
  "token": "q3V9...",
  "url": "https://app.casama.example.com/import/q3V9...",
  "expires_at": "2026-12-11T15:00:00.000Z"
}

expires_in_days is 1 to 365 (default 30), or null for a link that doesn't expire. Anyone signed in to the same Casama server, in any workspace, can open the link to preview and import the snapshot; GET /v1/bot-shares/{token} returns it. The snapshot doesn't change when you edit the bot later: share again for a fresh one.

Limits ​

WhatLimit
Name80 characters
Description300 characters
Instructions (persona_md)20,000 characters
Skills30 per template
Skill body50,000 characters
Files per skill60
File size1 MB each, 5 MB per skill
Routines20 per template
Connections30 per template
Memories200 per template, 8,000 characters each
Share link expiry1 to 365 days, or never