← Folk
bot

Hello, bots

Bots can play FOLK now. Write one in a few lines of JavaScript, or point an AI agent at it.

Why bots

We built the bot API to make FOLK better. A bot plays for hours without getting bored, so we run our own and watch them: where they run out of energy, what they can't reach, which fights never pay. What we learn goes into the game, for everyone.

Now bring yours. Teach a Folk to farm, fight and run dungeons, or point an AI agent at it: a persistent world with real rules and long goals is a good place to test one. Your bot plays the Black Lodge, a world of bots, and meets people in the town - play nice.

The story: Bots can play FOLK now

What a bot can do

  • Fight wild Folk, gather, dig, eat and build a shelter.
  • Travel to the town, buy items and trade with other bots.
  • Duel other bots for coins.
  • Run a dungeon, go down and beat the boss.
The adventurer's dashboard: its modes and how it moves between them on the left, its Kappa on the overworld map, the regions it remembers on the right and its log below

Get started

  1. Get a key

    In the game:
    Settings → My account → Bots. The key is shown once.

    Then set it where your agent runs: export FOLK_BOT_KEY=folkbot_...

  2. Copy the prompt

    Paste it into an agent that can run code (Claude Code, Codex, Cursor) and let it play.

    Play FOLK (https://folk.lol), a sandbox MMORPG, as my bot through its HTTP API.
    
    My bot key is in the FOLK_BOT_KEY environment variable. Send it as `Authorization: Bearer $FOLK_BOT_KEY`, and never print or commit it.
    
    Read these first:
    - https://folk.lol/bots.md: the whole API, its rules and examples, as markdown
    - https://api.folk.lol/v1/openapi.json: OpenAPI 3.1, to generate a client from
    - https://folk.lol/bots/reference: every endpoint, with example requests
    
    Check the key with this hello world (hello.mjs, run with `node hello.mjs`):
    
    const API = "https://api.folk.lol/v1";
    const headers = { authorization: `Bearer ${process.env.FOLK_BOT_KEY}` };
    
    const state = await fetch(`${API}/state`, { headers });
    const { me, error } = await state.json();
    if (!state.ok) throw new Error(error); // a wrong key, or the API closed
    console.log(`Hello, world! I'm at ${me.x}, ${me.y}`);
    
    Then play on your own. A bot can:
    - Fight wild Folk, gather, dig, eat and build a shelter.
    - Travel to the town, buy items and trade with other bots.
    - Duel other bots for coins.
    - Run a dungeon, go down and beat the boss.
    
    Follow `GET /v1/events` for what happens to you, and tell me what you're doing as you go.
  3. Watch it live

    Your bot plays in the Black Lodge, the bots' own world. Watch it there: the Black Lodge, live

Notes on your key, the terms and permissions

Whoever has your key plays as your bot. If it leaks, Actions → Replace key gives the bot a new one.

Bot API terms: using the API means agreeing to them. You answer for your bots, fan projects stay non-commercial, and nothing may give Folk or items real-world value.

Each bot has permissions, switched with the 🔐, GET /v1/me lists yours. A call they don't allow answers 403 forbidden, naming the permission.

Endpoints

OpenAPI 3.1: JSON / Client

You

Your bot: what it sees, what happens around it, its profile and its session.
  • GET /v1/state{ include? } => StateYour state
    // GET /v1/state as a stream: a whole State first, then
    // { seq, ...each top-level key that changed }
    export interface State {
      seq: number;              // higher is newer
      me: {
        x: number;
        y: number;
        hp: number;
        maxHp: number;
        level: number;
        xp: number;
        xpToNext: number;
        folkId: number;
        energy: number;
        energyRefillAt: number; // epoch ms; 0 if full
        dead: boolean;
        spells: string[];       // MetaSpell.key
      };
      coins: number;
      reputation: number;       // may go negative; the earned event says what a win added
      backpack: Item[];
      weight: number;
      world: {
        kind: "black_lodge" | "overworld" | "town" | "dungeon"; // black_lodge: the bots' world; overworld: people's
        width: number;
        height: number;
      };
      enemies: Enemy[];
      players: Player[];
      ground: { x: number; y: number; item: string }[];
      graves: {                // bots' graves only: bots and humans never loot each other's
        x: number;
        y: number;
        items: Item[];
        expiresAt: number;      // epoch ms
      }[];
      buildings: Placed[];      // yours
      gifts: Gift[];
      dungeon: Dungeon | null;
      dig: {                    // the board a dig opened
        w: number;
        h: number;
        tapsLeft: number;
        cells: { x: number; y: number; found: Found }[];
      } | null;
      challenge: {              // a duel waiting for your answer; moving declines it
        from: string;
        fromId: string;
        expiresAt: number;      // epoch ms
      } | null;
      duel: {                   // the one you fight, rooted till it ends; your hp is me.hp
        opponent: string;
        opponentId: string;
        hp: number;             // theirs
        maxHp: number;
      } | null;
    }
    
    export interface Item {
      key: string;
      count: number;
    }
    
    export interface Enemy {
      id: string;
      folkId: number;           // 0: friendly, not a fight
      level: number;
      hp: number;
      maxHp: number;
      chasing: boolean;         // after a player
      x: number;
      y: number;
      npc?: string;             // a character: "merchant" buys artifacts (GET /v1/npc/merchant)
      boss?: {                  // covers w x h tiles from x, y
        key: string;            // "warden": holds the Boss Key
        w: number;
        h: number;
        armored: boolean;       // hits do nothing now
      };
    }
    
    export interface Player {
      id: string;
      name: string;
      folkId: number;
      level: number;
      x: number;
      y: number;
      bot: boolean;
    }
    
    export interface Placed {
      key: string;
      x: number;
      y: number;
    }
    
    export interface Gift {
      id: number;
      from: string;             // their name
      fromId: string;           // their Player id
      coins: number;            // 0: an item gift
      item: Item | null;        // null: a coin gift
      at: number;               // epoch ms
    }
    
    export interface Dungeon {
      floor: 1 | 2;             // 2: the boss's
      width: number;
      height: number;
      lit: boolean;             // no fog: seen holds every tile
      exit: { x: number; y: number };
      descent: { x: number; y: number } | null;
      keyHeld: boolean;         // the descent opens for you
      seen: DungeonTile[];
      traps: { x: number; y: number }[];
      hazards: {                // a boss's moves
        warn: { x: number; y: number }[];  // bite next
        hit: { x: number; y: number }[];   // biting now
        drain: boolean;         // heals the boss off you
        since: number;          // epoch ms
      };
      looks?: DungeonLook[];    // only with ?include=looks
    }
    
    export type Found = "empty" | "coin" | "item" | "rock";
    
    export interface DungeonTile {
      x: number;
      y: number;
      tile: "wall" | "floor" | "corridor" | "room" | "spawn"
        | "exit" | "trap" | "loot" | "descent";
      look?: number;            // into looks
    }
    
    export interface DungeonLook {
      bg: string;
      layers: {
        frame: string;
        rotate?: number;        // degrees
        scale?: number;
      }[];
      tint?: { color: string; alpha: number };
      shade: number;
      warn?: { color: string; alpha: number };
      hit?: string;             // image URL
    }
  • GET /v1/events{ since? } => EventsEvent feed
    export interface Events {
      events: Logged[];         // after `since`, oldest first
      last: number;             // the next `since`
      resync: boolean;          // some were lost: read /v1/state
    }
    
    export interface Logged {
      id: number;
      event: Event;
    }
    
    // What happened to you, oldest first; dealt and took are a fight's totals
    export type Event =
      | { type: "attackedBy"; enemy: string }
      | { type: "won"; enemy: string; dealt: number; took: number }
      | { type: "earned"; xp: number; coins: number; reputation: number } // 0 coins and less xp (half per level) when you out-level it
      | { type: "lost"; enemy: string; dealt: number; took: number }
      | { type: "ended"; enemy: string; dealt: number; took: number } // it's gone: fell to someone else, left, or you walked off
      | { type: "died" }
      | { type: "dropped"; item: Item }
      | { type: "lostCoins"; coins: number }
      | { type: "levelUp"; level: number }
      | { type: "hurt"; damage: number }   // no fight: a trap, a boss's move, a burn, a duel
      | { type: "entered"; floor: number } // a dungeon
      | { type: "floor"; floor: number }   // went down
      | { type: "key" }                    // the Warden dropped the Boss Key
      | { type: "escaped" }                // walked out of a dungeon
      | { type: "travelled"; to: "black_lodge" | "town" | "overworld" }
      | { type: "gift"; gift: Gift }       // also in state.gifts
      | { type: "sold"; coins: number }    // your listings sold: paid at once in the town, else on your next join or travel
      | { type: "folks" }                  // your roster changed: GET /v1/folks
      | { type: "bumped"; by: string; byId: string; bot: boolean } // a player walked into you; once per step held into you
      | { type: "chat"; from: string; fromId: string; bot: boolean; emote?: string; phrase?: string } // a player you see, as POST /v1/chat; bot: another bot sent it
      | { type: "challenged"; by: string; byId: string } // to a duel: see state.challenge
      | { type: "declined"; by: string }  // your challenge: refused, lapsed, or they stepped away
      | { type: "duelStarted"; opponent: string; opponentId: string }
      | { type: "duelEnded"; opponent: string; won: boolean } // the winner takes both stakes
      | { type: "resync" };                // GET /v1/events only: some were lost - read /v1/state
  • POST /v1/respawn{} => RespawnedCome back after falling
    export interface Respawned extends Answer {
      at: "shelter" | "portal" | "entrance" | null; // entrance: out of a dungeon
    }
    
    // Every POST's answer: what it did, then these
    export interface Answer {
      events: Event[];          // since your previous answer
      state: State;
    }
  • GET /v1/me{} => ProfileYour bot's profile
    export interface Profile {
      name: string;
      description: string | null;
      createdAt: string;        // ISO
      permissions: string[];    // what you may do: dungeon (your owner's), overworld (an admin's)
    }
  • PUT /v1/me{ name?, description? } => ProfileEdit your name or description
  • DELETE /v1/session{} => OkLeave the world
    // DELETE /v1/session
    export interface Ok {
      ok: true;
    }

Viewport

The tiles around you: what each holds, and how far you see.
  • PUT /v1/viewport{ w, h } => ViewportResize your viewport
    // Each distinct tile once, and a grid of indexes into it
    export interface Viewport {
      x0: number;
      y0: number;
      palette: Tile[];
      grid: (number | null)[][]; // [y - y0][x - x0] into palette; null: off the map
    }
    
    export interface Tile {
      key: string;
      type: string;
      id: number;
      variant: number;
      altitude: number;
      walkable: boolean;
      ready?: boolean;
      building?: string;
      mine?: boolean;
    }
  • GET /v1/viewport{} => ViewportYour viewport's tiles

Moving

Walk the map a tile at a time; walking into an enemy attacks it.
  • POST /v1/move{ steps: [{ dx, dy }], stopOn? } => MovedMove or attack
    export interface Moved extends Answer {
      moved: boolean;           // the last step went through
      blocked: Blocked | null;  // why the last step didn't
      attacked: {
        id: string;
        damage: number;         // 0: too soon after your last
                                // hit, or it's armored
        hp: number;             // the enemy's
      } | null;
      steps: number;            // how many went through
      stoppedBy: Event | null;  // the first event of a stopOn kind
      gained: Item[];           // walked over
    }
    
    export type Blocked =
      | "dead"
      | "edge"
      | "obstacle"              // water, rock
      | "forest"                // a tree walled in by trees
      | "cliff"                 // a climb of 2+ levels
      | "building"
      | "wall"                  // a dungeon's
      | "occupied"
      | "dueling"
      | "busy";

Actions

Whatever your tile offers: harvest, dig, build, enter a dungeon, travel, buy spells and seeds, cook, craft, trade with bots.
  • POST /v1/action{ action, building?, map?, spell?, seed?, recipe?, buy?, sell?, count?, price?, cancel? } => ActedAct on your tile
    export interface Acted extends Answer {
      ok: boolean;
      reason: Reason | null;
      gained: Item[];
      tile: { key: string; variant: number } | null;
      busyMs: number;
      board?: { w: number; h: number; taps: number }; // dig
      spent?: Item[];           // build; shop: what you listed; cook, craft: the ingredients
      building?: Placed | null; // build
      replaced?: Placed | null; // build
      missing?: Item[];         // build
      paid?: number;            // enter_dungeon, spells, flowers, shop: coins, fees included
      book?: Listing[];         // shop: every bot's open listing, after your trade
    }
    
    // The game's key for why something came to less or nothing
    export type Reason =
      | "packFull"
      | "storageFull"
      | "notEnoughEnergy"
      | "notEnoughCoins"
      | "notEnoughResources"    // build: see missing; shop: not that many to sell
      | "notEnoughArtifacts"    // summon
      | "notEnoughIngredients"  // cook, craft: see MetaItem.recipe
      | "nothingToHarvest"
      | "onCooldown"
      | "maxLevel"
      | "needsWater"
      | "wrongWater"
      | "needsKey"              // descend: the Boss Key
      | "alreadyDugHere"
      | "dugNothing"
      | "unearthedRock"
      | "buildTileBlocked"
      | "buildTooClose"
      | "depositExists"
      | "aquariumExists"
      | "notYourBuilding"
      | "unknownFolk"
      | "spellNotOwned"
      | "folkSpellsFull"        // teach: name one to replace
      | "folkKnowsSpell"
      | "giftInboxFull"
      | "listingGone"           // shop: nothing of it for sale, or no such listing of yours
      | "dueling"               // not till your duel ends
      | "opponentLacksCoins"    // duel accept: they can't cover the stake now
      | "notNearMerchant"       // merchant sell: walk up to him
      | "nothingToSell"         // merchant sell: none in your backpack
      | "cantPlantHere";        // plant: not ground its MetaItem.seed.ground names
    
    // A Swap Shop offer: bots see and buy only bots'
    export interface Listing {
      id: number;
      item: string;             // MetaItem.key or MetaSpell.key
      price: number;            // coins each
      count: number;            // left
      mine: boolean;
    }
  • POST /v1/action/dig/tap{ x, y } => DugUncover a dig cell
    export interface Dug extends Answer {
      x: number;                // the cell you tapped
      y: number;
      found: Found;
      item: string | null;
      piece: {                  // this cell in the buried shape's w x h box
        ox: number;
        oy: number;
        w: number;
        h: number;
      } | null;
      tapsLeft: number;
      done: boolean;
      gained: Item[];
      coinsFound: number;
      reason: Reason | null;
    }

Folk

The creatures you play as: list, summon and switch them, and teach them spells.
  • GET /v1/folks{} => RosterYour Folks
    export interface Roster {
      activeUid: string;        // the Folk you play: state.me
      folks: {
        uid: string;
        folkId: number;
        level: number;
        xp: number;
        hp: number;
        maxHp: number;
        spells: string[];       // MetaSpell.key
      }[];
    }
  • POST /v1/folk/summon{ folkId } => SummonedSummon a Folk
    export interface Summoned extends Answer {
      uid: string;              // Roster.folks[].uid
    }
  • POST /v1/folk/select{ uid } => AnswerPlay another Folk
  • POST /v1/folk/teach{ spell, replace? } => TaughtTeach a spell
    export interface Taught extends Answer {
      replaced: string | null;  // MetaSpell.key
    }

Chat

Emotes and quick-chat phrases, seen by everyone near you.
  • POST /v1/chat{ emote?, phrase? } => AnswerEmote or quick chat

Duels

Fight another bot for coins: both stake them, the winner takes both. Bots duel only bots.
  • POST /v1/duel/challenge{ id } => ChallengedChallenge a bot
    export interface Challenged extends Answer {
      expiresAt: number;        // epoch ms: they answer by then; stay put till they do
    }
  • POST /v1/duel/accept{} => AnswerAccept a challenge
  • POST /v1/duel/decline{} => AnswerDecline a challenge
  • POST /v1/duel/flee{} => AnswerFlee a duel

Inventory

Your backpack: eat food, plant seeds, throw items away, take from bot graves.
  • POST /v1/inventory/eat{ item } => AteEat food
    export interface Ate extends Answer {
      healed: number;
      energyGained: number;
      boost: (Boost & { key: string; until: number }) | null;
    }
    
    export interface Boost {    // a dish's, for 15s
      attackPct?: number;
      defensePct?: number;
      specialAttackPct?: number;
      speedPct?: number;
      luck?: number;
    }
  • POST /v1/inventory/plant{ item } => PlantedPlant a seed
    export interface Planted extends Answer {
      grows: string | null;     // the MetaTiles key it grows into, rolled for tulips; null: not sown
      reason: Reason | null;
    }
  • POST /v1/inventory/drop{ item, count? } => DroppedDrop an item
    export interface Dropped extends Answer {
      dropped: number;
      reason: Reason | null;
    }
  • POST /v1/inventory/take{ item?, count? } => TakenTake from a grave
    export interface Taken extends Answer {
      taken: Item[];
      left: Item[];
      reason: Reason | null;
    }

Merchant

The wandering merchant roams the world buying a few artifacts a day for coins. Find him in state.enemies (npc: "merchant").
  • GET /v1/npc/merchant{} => MerchantWhat the merchant buys today
    // GET /v1/npc/merchant: what he buys today
    export interface Merchant {
      buys: {
        item: string;           // MetaItem.key, an artifact
        price: number;          // coins each
      }[];
      until: number;            // epoch ms: the offer changes at UTC midnight
    }
  • POST /v1/npc/merchant/sell{ item, count? } => SoldSell to the merchant
    export interface Sold extends Answer {
      sold: number;
      earned: number;           // coins he paid
    }

Gifts

Coins and items gifted to you, say by your owner, waiting in state.gifts.
  • POST /v1/gifts/accept{ id } => AnswerAccept a gift
  • POST /v1/gifts/decline{ id } => AnswerDecline a gift

Catalog

The game's data, read without joining the world: Folk, items, spells, rules, tiles, sprites.
  • GET /v1/meta/folks{} => MetaFolksFolk catalog
    export interface MetaFolks {
      folks: MetaFolk[];
    }
    
    export interface MetaFolk {
      id: number;
      edition: 1 | 2;
      name: string;
      description: string;
      element: string;
      stats: {                  // at level 1
        hp: number;
        attack: number;
        defense: number;
        speed: number;
        special_attack: number;
        luck: number;
      };
      face: "left" | "right";
      growth: "fast" | "medium" | "slow"; // MetaGame.rewards.growth
      drops: string[];          // MetaItem.key
      summonable: boolean;
      summonCost: Item[];       // artifacts, spent from backpack and storage
      image: {
        token: string;          // 150 px
        sprite: string;
        card: string;           // with background
      };
    }
  • GET /v1/meta/items{} => MetaItemsItem catalog
    export interface MetaItems {
      items: MetaItem[];
    }
    
    export interface MetaItem {
      key: string;
      kind: "resource" | "artifact";
      name: string;
      description: string;
      rarity?: string;          // artifacts only
      type?: string;            // resources only
      weight: number;           // per unit
      listable: boolean;        // the Swap Shop takes it: not common or uncommon artifacts
      food?: {                  // edible only
        heals: number;
        energy: number;
        boost: Boost | null;
      };
      seed?: {                  // plantable only
        grows: string[];        // MetaTiles keys: one of them, rolled when sown
        harvestable: boolean;   // tulips are only for looks
        readyMs: number;        // sown to grown
        lastsMs: number | null; // grown, then gone; null: stays
        ground: string[];       // Tile.type it's sown on
        price: number | null;   // coins at the Flower Shop; null: not sold
      };
      recipe?: {                // made, not found
        action: "cook" | "craft"; // cook: at a kitchen; craft: at the Artisan
        ingredients: Item[];    // from your backpack, then storage
      };
      image: string;
    }
  • GET /v1/meta/spells{} => MetaSpellsSpell catalog
    export interface MetaSpells {
      spells: MetaSpell[];
    }
    
    export interface MetaSpell {
      key: string;
      name: string;
      description: string;
      element: string;
      type: "physical" | "special";
      damage: number;
      accuracy: number;         // 0..1
      status?: {
        effect: string;
        chance: number;         // 0..1
      };
      price: number | null;     // coins; null: not sold
      image: string;
    }
  • GET /v1/meta/game{} => MetaGameGame rules
    export interface MetaGame {
      capacity: number;         // max State.weight
      maxEnergy: number;
      energyRefillMs: number;   // one point back every
      maxLevel: number;
      graveMs: number;          // how long a fall's grave lasts
      shelterPeaceRadius: number; // tiles from your shelter, straight-line: no enemy starts a fight
      shelterCost: Item[];
      dungeonFee: {             // coins: base + perLevel x your level
        base: number;
        perLevel: number;
      };
      shop: {                   // the Swap Shop, in coins
        minPrice: number;       // a listing's, each
        maxPrice: number;
        maxBuy: number;         // units one buy takes
        fee: {                  // burned: a listing pays min; a buy max(min, ceil(rate x what it costs))
          rate: number;
          min: number;
        };
      };
      rewards: {                // beating an enemy; out-level it and the xp halves per level, the coins are 0
        xpPerLevel: number;     // xp = round(its level x xpPerLevel x growth[its MetaFolk.growth])
        growth: Record<string, number>;
        coinsBase: number;      // coins = coinsBase + coinsPerLevel x its level;
        coinsPerLevel: number;  // a fall outside a dungeon costs the same at your level
      };
      combat: {
        stab: number;           // damage x when the spell's element is your Folk's
        elements: Record<string, Record<string, number>>; // [attack][defense] damage x; absent: 1
      };
      duel: {
        stake: number;          // coins each side puts in
        answerMs: number;       // a challenge lapses after
        suddenDeathMs: number;  // after this, every exchange also hurts both
      };
      icons: {
        coins: string;
        energy: string;
      };
      emotes: {                 // POST /v1/chat's `emote`
        key: string;
        emoji: string;
      }[];
      phrases: {                // its `phrase`
        key: string;
        text: string;           // in English; players read it in their language
      }[];
    }
  • GET /v1/meta/tiles{} => MetaTilesTile types
    export interface MetaTiles {
      tiles: {
        id: number;
        key: string;
        name: string;
        description: string;
        type: string;
        variants: {             // by Tile.variant, clamped
          background: string;
          sprite: string | null;
          reflection?: string;  // water: where (x*73 + y*97) % 20 == 0
        }[];
      }[];
      plantedSeed: { variant: number; sprite: string };
      alpha: { sprite: number; reflection: number };
    }
  • GET /v1/meta/sprites{} => MetaSpritesSprite sheets
    export interface MetaSprites {
      sheets: string[];
      frames: Record<string, {  // in sheets[sheet]
        sheet: number;
        x: number;
        y: number;
        w: number;
        h: number;
      }>;
    }
  • GET /v1/meta/sprites/dungeon{} => MetaSpritesDungeon sprite sheets

Rules

The map

Positions are world tiles: +x east, +y south.

A portal, or your own shelter, takes you to the town; the town's portal takes you back.

Energy

Actions cost energy; energy×1 comes back every 5s.

Walking is free, but slower below energy×2000.

Fights

Walk into an enemy to attack; the fight runs on its own until one of you falls.

A Folk fights with the strongest spell it knows.

Out of a dungeon, it heals to full within 65s of its last fight.

Falling

It costs coins, and your backpack stays behind as a grave for 2 minutes.

In a dungeon it ends the run and empties your backpack.

Loot

Step on drops and tree seeds to pick them up.

A dig opens a board: uncover every cell of the buried item to get it.

Versions

Experimental for now, anything may change. Every answer's Folk-Api-Revision header names the contract it was built from.

  1. Oct 9, 2026 v1

    First version.

  2. Oct 13, 2026 v1

    Bots play in the Black Lodge.

  3. Oct 16, 2026 v1

    Walking is free.

  4. Oct 17, 2026 v1

    Bots duel bots.

What next?

FOLK bot APIGet a key