First Week With the Buffy API: A Step-by-Step Integration Guide

You don’t need to “read the whole API spec” before you ship something useful with Buffy.

For most teams, the fastest path is to integrate in small, testable steps:

authenticate
send one message into the behavior core
inspect activities and event outcomes
wire in a loop for updates, reminders, and (later) webhooks

This guide is the “week 1” plan. You’ll do one meaningful thing per day, so you can validate assumptions early and reduce integration risk.

What you’ll learn

How to authenticate and make your first POST /v1/message call

How to list and update activities (habits, tasks, routines)

How to build a feedback loop with webhooks and reminders (next steps)

If you want the contract-first entry point, start with:

Day 1: Set up auth and your first `POST /v1/message`

Buffy uses Bearer auth:

Authorization: Bearer <YOUR_API_KEY>

Make your first call to send a natural language instruction into the behavior core:

curl -X POST https://api.buffyai.org/v1/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Set up a morning startup: water + 10-minute planning between 7:30 and 9:00."}'

What you should do today:

verify the response returns a structured reply (not an error)
confirm that the routine/activities exist by asking for “today’s state” next

Why this matters: /v1/message is the easiest way to validate that your behavior core wiring works end-to-end.

Day 2: Inspect activities (habits, tasks, routines)

Once you’ve created something, list it:

curl https://api.buffyai.org/v1/activities/today \
  -H "Authorization: Bearer YOUR_API_KEY"

What you should do today:

check that the activities reflect your intent (type + schedule window)
verify that the activity identifiers are stable for updates

You’re building the “read side” of your integration.

Day 3: Update an activity without rewriting behavior rules

Integration failures often happen when teams “re-implement” behavior rules client-side.

Instead, update the activity state using the activities endpoints. The exact payload shapes are in OpenAPI; the key pattern is:

send an update
let Buffy apply the behavior rules consistently

Example (conceptual):

curl -X PUT https://api.buffyai.org/v1/activities/<activityId> \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Shift this window for this week based on what happened.","window":"07:45-09:15"}'

What you should do today: