You do not need a PDF or a stale wiki page to integrate with Buffy. The running API exposes a first-class OpenAPI 3 description plus interactive docs—treat those as canonical and use this post as a narrow map of what to open first.
Base URL and spec
- API base:
https://api.buffyai.org - Machine-readable spec:
GET /openapi.yamlon that host (Swagger UI is typically at/swagger).
Regenerate clients, mock servers, or contract tests from the YAML when you want lock-step typing with production.
Authentication
Almost all integration traffic uses:
Authorization: Bearer <API_KEY>
Create and rotate keys from Account → API keys on buffyai.org. Keep keys out of frontends; call the API from your server, automation, or OpenClaw skill.
Core routes (first week of integration)
Exact schemas are in OpenAPI; names below match typical v1 usage:
| Area | Method and path | Role |
|---|---|---|
| Identity | GET /v1/auth/me |
Confirm the token and user context. |
| Message | POST /v1/message |
Send user text or structured commands into the behavior core; primary path for conversational agents. |
| Activities | GET /v1/activities |
List habits, tasks, and routines. |
| Activities | PUT /v1/activities/:id |
Update state (e.g. completion, schedule tweaks) without reinventing rules client-side. |
| Activities | DELETE /v1/activities/:id |
Remove an activity when your UX allows delete. |
| Settings | GET / PUT /v1/users/:id/settings |
User preferences the core should respect. |
| API keys | POST /v1/users/:id/api-keys, DELETE /v1/api-keys/:id |
Programmatic key management when building operator tools. |
Optional capabilities (MCP streamable HTTP, webhooks, clan APIs, billing introspection) are documented in the same spec—open the YAML and filter by tag or path prefix.
MCP and automation
Tools such as Cursor can call POST /mcp with the same Bearer identity to list and invoke MCP tools backed by your user. Cron jobs and CI often use POST /v1/message or activity endpoints only; see habit tracking for developers for patterns.
Relation to the architecture story
The API is the thin wire; the product story is one behavior core and multi-channel adapters:
- Buffy API: Plug Your App Into the Behavior Engine
- Building Multi-Channel Bots on Top of One Behavior Core
- Activity model: habits, tasks, routines
Next step
Integration guide: Buffy API: Plug Your App Into the Behavior Engine. Product orientation: What Is Buffy Agent?.