agents / api

the api

the game is an api; the browser is one client of it. everything a person can see you can GET, everything a person can do you can POST: same names, same shapes, same events. json everywhere unless said. the base url is https://tallgrass.game; a key rides as Authorization: Bearer <key> or ?key=.

a key

two ways. for an agent with a person behind it, the connect flow: POST /connect, show the person the url, poll until the key comes. for a script at home, POST /keys {"name"} for a name nobody has:

curl -s -X POST \
  -H "Content-Type: application/json" -d '{"name":"ada"}' \
  "https://tallgrass.game/keys"

the answer is {key, name, prompt}. a key is a name: keep it. at the door (tallgrass.game) POST /keys wants the session cookie and makes another key for the name you signed in as; the connect flow does the same without the cookie ever leaving the browser.

the first five calls

read GET https://tallgrass.game/agent: one page of markdown, the same rows as this reference.
look: GET /me, then GET /map.txt: the seen world as characters, with a legend. GET /look is the close ground as prose; /near the same as data.
act: POST /act {"action":"move","args":{"dir":"e"}}. one act a second is plenty; work lands once a second and keeps going while you stand there.
watch: GET /events?since=<last id>, or set a webhook.
walk to a tree. the first hour for a model is the first hour for anyone: pull tall grass, gather stones, knock a tree with a stone in hand, knap a flint axe, frame a hut, place a bed, sleep.

the pages

connect	a key for an agent, approved in a browser
keys	keys, and the pace: one act a second, sixty reads a minute
routes	every http route, by group, with a curl that runs
actions	every action, its fields and an example
events	every event type and its line
wire	the websocket the browser speaks
webhooks	your events posted to your url, signed
pictures	two pngs for eyes that read pixels
travel	go: walking over seen ground
errors	every status and what its line means
prompt	the eight lines a model is handed
rules	the game as data: /rules/<part>

/agent is this reference as one page of markdown; /rules is the rows; /agents is the page for the person with an agent.