Bots & groups API

This is the contract behind Bots and Bot groups. Desktop and the iOS app both speak it; it is documented here because anything reaching a Flowly gateway has to know the same bounds they do.

Bot methods

Everything a client may ask one bot to do. A method not on this list is refused rather than forwarded, and each carries its own timeout ceiling.

Most carry a 30-second ceiling; chat.send, model.list, plan.resume, goal.resume and cron.run are allowed 60 seconds.

Permission values

Internal sessions

Some sessions belong to host orchestration rather than to a reader, and are not offered as conversations: those prefixed desktop:profile-inbox:, desktop:profile-room: and desktop:profile-task:. Sessions reached from a client carry a desktop:, web: or ios: prefix.

Group methods

Capabilities

A host advertises what it supports, so a client never has to guess or infer it from a version number:

{
  "modes": ["panel", "council"],
  "maxMembers": 6,
  "councilRounds": 3,
  "councilTurns": 10,
  "summaries": true,
  "historyPagination": {
    "defaultPageSize": 50,
    "maxPageSize": 100,
    "cursor": "opaque-v2"
  },
  "retention": {
    "model": "retain-beyond-window",
    "liveWindow": 1000,
    "durableHistory": true
  },
  "usage": {
    "tokens": true,
    "cost": "catalog-priced",
    "memberBreakdown": 24
  },
  "memberPolicies": {
    "values": ["always", "mentioned"],
    "default": "always",
    "everyoneOverrides": true,
    "silentWhenNoneAlways": true
  },
  "errorCodes": ["…"],
  "roomEvents": ["full-v1", "delta-v1"],
  "storage": "sqlite-wal",
  "legacyJsonMigration": "verified-copy-preserve-source"
}

modes advertises both shapes the host can run, and clients send mode on create and update. A payload without it means panel, which is what every group did before the field existed — so a client that does not know it still creates groups that behave correctly, and an update that omits it leaves the shape alone rather than resetting it.

Two of these deserve reading twice:

• retention.liveWindow is not how many messages exist. It is what the group carries in memory and in a snapshot payload. Durable history is not bounded by it. A client that treats the window as the total will report a group as shorter than it is the moment it outgrows the window.
• usage.cost is catalog-priced. Tokens are counted for every group; money appears only when the model catalogue can price the models involved. A client must be ready to render a group that reports tokens and no cost.

Member reply policies

memberPolicies describes who answers a message that named nobody:

• values — always and mentioned
• default — always, which is what every group did before the field existed, so a client that does not know the field still describes its groups correctly
• everyoneOverrides — an explicit @everyone reaches members set to mentioned
• silentWhenNoneAlways — a group where nobody is always records an unaddressed message and starts no run. Clients should say so rather than leave somebody waiting for a reply that is not coming.

Policies are sent as a map of member name to policy. Absent means unchanged on an update, not cleared — otherwise an older client renaming a group would quietly make every member answer again.

Error codes

A failure is named by a code, and the client translates the code. The sentence that travels with it is for a log, not for a reader.

INVALID_PARAMS is deliberately absent from that table. It means a client sent something malformed, so the person reading it is the one debugging that client, and English is the right language for them.

Gateway identity

A running gateway states what it is on /health, which needs no token:

{
  "status": "ok",
  "service_id": "ai.flowly.gateway",
  "version": "3.2.0",
  "runtime_owner": "desktop",
  "auth_required": false,
  "capabilities": ["tool_events", "queue_while_busy", "…"]
}

• service_id is always ai.flowly.gateway. A client that sees a different value should treat the response as coming from something that is not Flowly.
• version is omitted by a source checkout that cannot state a real version, rather than reported as 0.0.0-dev — which would compare as older than every release.
• runtime_owner is desktop, cli or manual, taken from the environment the starter set, or from the executable's own path. It is omitted when neither says anything definite, so a reader falls back to its own classification rather than acting on a guess.

Storage

Groups are kept in one SQLite database, write-ahead-logged so several processes can use it safely.

Migrations run forward one step at a time and stamp each version before the next begins, so a crash between two steps cannot leave finished work behind an unchanged version number.

A database written by a newer Flowly is left untouched by an older one, which reports an unrecognised schema rather than editing it. Groups stop working on the older build; the data is not damaged.

Limits

Sessions

Each member keeps a private session for each group, keyed desktop:profile-room:<groupId> inside that bot's own directory. Group attachments are stored with a group- prefix, which is what keeps the ordinary media cleanup — which ages out generated pictures — from reaching a file a message still points at.