Where is the official OpenAPI document?

Production serves the spec at https://api.buffyai.org/openapi.yaml (and commonly /swagger for interactive docs). Use that as the source of truth for paths and schemas; blog tables can lag minor releases.

How do I authenticate?

Send Authorization: Bearer . Create keys in the Buffy web app under Account → API keys. Some server-side or operator flows may document additional headers for attribution; the OpenAPI description field notes those when they apply.

What is the single most important endpoint for chat-like flows?

POST /v1/message carries normalized user input into the behavior core and returns replies plus intent handling. Pair it with GET/PUT /v1/activities when you need direct CRUD on habits, tasks, or routines.

Buffy API reference overview: OpenAPI, auth, and core routes

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.yaml on 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:

Next step

Integration guide: Buffy API: Plug Your App Into the Behavior Engine. Product orientation: What Is Buffy Agent?.