API overview
Let a program of your own drive a workspace: start agents, read their replies, follow who is waiting, all with a token you can revoke.
The API lets a program on your computer drive a workspaceOne project folder and everything open for it.Glossary → the way you do. Think of an orchestrator that hands work to agents, a dashboard of who is waiting, or a script your CI calls.
Paste this into your coding agent to build a script that lists the agents waiting on you.
Show the prompt
Write me a small script that lists the agents in my Hivemind workspace that are waiting on me, using a read-only API token. 1. Ask me which project folder is the workspace. Check Hivemind runs with it open: `hive ctl agents` must not exit 3. If it does, ask me to open it with `hivemind <folder>`. 2. Make a token with the smallest role, `view`: `hive grant create waiting-list -w <folder> --role view --expires 30d --json`. The output holds `token` and `socket`. Never print the token in this chat and never write it to a file git tracks. Put it in a git-ignored `.env` as `HIVE_DRIVE_TOKEN`, with `HIVE_DRIVE_SOCK` (the socket) and `HIVE_WORKSPACE` (the folder). 3. Check the token works: with those variables set, `hive ctl agents --json` prints the workspace's agents. 4. Write the script in TypeScript or Python with the `hivemind-api` SDK (it comes with the app: `npm install ~/.hivemind-app/sdk/hivemind-api.tgz` or `pip install ~/.hivemind-app/sdk/python`; on Windows the folder is `%LOCALAPPDATA%\hivemind\sdk`). `connect()` reads the token, workspace and socket from those variables. Call `hive.agents.list()` and print each agent whose `waiting` field is set, with its name and what it waits on. 5. Run it and show me the output. At the end, tell me the token's id from `hive grant list` and that `hive grant revoke <id>` takes it back. REFERENCE https://hivemind.griiken.com/guide/api.md
- Your program → drive socket: a hello with its token.
- Each call → the token's role. Allowed: it reaches the workspace, its agents, terminals and board. Not allowed: refused with
FORBIDDEN.
How it works
Your program talks to the app through a local connection that only your user can open (drive.sock, a named pipe on Windows). The app serves it, or hive host when that runs instead.
| Piece | What it is |
|---|---|
| Token | A secret your program sends first. You make it in Settings → API access or with hive grant create. It is shown once. |
| Role | What the token may do: view, edit, terminals or agents. These are the same roles people get when you share a workspace. |
| Messages | One line of JSON per message, both ways. You send calls; the app sends answers and events. |
Why it works this way
A token reaches only the workspaces you name, at one role. A call the role does not allow is refused before it runs. Revoking a token closes its connections at once. So a program never does more than you chose, and never for longer than you allow.
Whatever its role, a program cannot share the workspace, let people in, change their roles, or make or revoke tokens. Those stay with you.
The terminals and agents roles can still change files and run any command, git push included. They do it through a shell they type into, or an agent they start.
Write a client
Use the hivemind-api SDK for TypeScript or Python: Connect and call walks through it. For any other language, the Protocol page has the raw messages.
What to do with it
Make an API token
Connect and call
Methods by role
Protocol
Without writing a client
hive ctl speaks the same API. To act as the program, give it the token:
export HIVE_DRIVE_TOKEN=hgr_…
export HIVE_WORKSPACE=~/work/api # only when the token reaches several workspaces
hive ctl agents --json
hive ctl spawn --agent claude --prompt "Run the tests" # needs the agents roleA tool's service gets its own token this way. It is made when the service starts and revoked when it stops.
Last validated for Hivemind 2026.10.3.