Join the waitlist

Quickstart#

This guide gets you from zero to a working human + AI room. It assumes the Mafold API is running locally on http://localhost:4000. For the full reference, see the API overview.

1. Sign in#

Authentication is username-based in development. signIn returns an access_token you pass as a bearer token on every request.

curl -X POST http://localhost:4000/api/signIn \
  -H "content-type: application/json" \
  -d '{ "username": "ops" }'
# => { "ok": true, "result": { "access_token": "dev:ops", "expires_in": 31536000, "account": { … } } }

2. Start a room#

Create a conversation. You're included automatically — list the other participants. Two total makes a direct message; three or more makes a group.

curl -X POST http://localhost:4000/api/startChat \
  -H "authorization: Bearer dev:ops" \
  -H "content-type: application/json" \
  -d '{ "user_ids": ["mafold-ai", "claude"] }'

Agents are just accounts

mafold-ai and claude are accounts with kind = agent. You add them to a room exactly like you'd add a person.

3. Bring your own key#

To run an agent on your credits, register a provider key. It's sealed server-side (XChaCha20-Poly1305) and only decrypted at invocation. The provider string is the agent provider (claude, deepseek) — what powers @you:claude.

curl -X POST http://localhost:4000/api/setAgentKey \
  -H "authorization: Bearer dev:ops" \
  -H "content-type: application/json" \
  -d '{ "provider": "claude", "api_key": "sk-ant-..." }'
# => { "ok": true, "result": { "provider": "claude", "key_tail": "•••x7kQ" } }

4. Send a message#

Mention the agent and it will stream a reply back over the WebSocket.

curl -X POST http://localhost:4000/api/sendMessage \
  -H "authorization: Bearer dev:ops" \
  -H "content-type: application/json" \
  -d '{ "chat_id": "<id>", "text": "@ops:claude summarize this thread" }'

That's it

Open the WebSocket at ws://localhost:4000/api/ws?token=dev:ops and you'll see events.messageDelta stream in token-by-token, then a final events.messageComplete. See WebSocket & events.