API v2

GET /me

The key owner's own profile. Costs 1 read.

{
  "id": "usr_…",
  "username": "puppy",
  "poundUsername": "puppyyyy123",
  "pronouns": "they/them",
  "terminology": "puppy",
  "createdAt": "2026-01-05T10:20:30.000Z"
}

poundUsername, pronouns, and terminology may be null.

GET /puppies

Your accepted friends, each with a capability summary. Ordered by your saved friend order. Costs 1 read.

{
  "puppies": [
    {
      "id": "usr_…",
      "username": "goodboy",
      "poundUsername": null,
      "pronouns": null,
      "terminology": "puppy",
      "profilePictureUrl": null,
      "capabilities": {
        "click": true,
        "message": true,
        "osc": true,
        "rest": false,
        "integrations": false
      }
    }
  ]
}

capabilities tells you which action types will work for that puppy right now:

Use GET /puppies/:id/actions for the full parameter metadata behind these flags.

GET /puppies/:id/actions

Everything you can send this puppy, with parameter metadata per action kind. Costs 1 read. Returns 404 PUPPY_NOT_FOUND if :id isn't one of your accepted friends.

{
  "actions": [
    {
      "type": "click",
      "params": {
        "intensity": { "min": 0, "max": 100, "optional": true },
        "duration": { "min": 0, "max": 30000, "optional": true },
        "message": { "maxLength": 150, "optional": true }
      }
    },
    {
      "type": "message",
      "params": { "message": { "minLength": 1, "maxLength": 150, "required": true } }
    },
    {
      "type": "osc",
      "subtypes": ["Shock", "Vibrate", "Sound", "Stop"],
      "maxIntensity": 60,
      "maxDuration": 5000,
      "online": true,
      "params": {
        "intensity": { "min": 0, "max": 60, "required": true },
        "duration": { "min": 300, "max": 5000, "required": true }
      }
    },
    {
      "type": "rest",
      "id": "cfg_…",
      "name": "Open the door",
      "description": "…",
      "icon": "door",
      "variables": [ /* config-defined variable schema */ ]
    },
    {
      "type": "integration",
      "id": "btn_…",
      "provider": "chaster",
      "providerLabel": "Chaster",
      "action": "add_time",
      "label": "Add 10 min",
      "icon": "lock",
      "params": { /* provider/action param schema */ }
    }
  ]
}

Per kind:

• click: always present. Optional intensity (0-100), duration (0-30000 ms), message (up to 150 chars).
• message: always present. Required message (1-150 chars).
. Officially unsupported, should work fine in client, Here for posterity.
• osc: present only when the puppy has a validated OpenShock device. Carries the puppy's own safety caps (maxIntensity, maxDuration) reflected into params.max, plus online (whether the device is currently reachable). Commands are also clamped server side to these caps regardless of what you send. subtype selects the effect.
• rest: one entry per active REST/webhook button. id is the config id to pass back, or the literal "legacy" for older single-endpoint setups. variables is the button's own variable schema.
• integration: one entry per delegated integration button. Pass id back; params describes any runtime parameters the action accepts (for example how much time to add).

POST /puppies/:id/actions

Send an action to a puppy. Consumes 1 action from the action budget. The body is a JSON object discriminated on type.

{ "type": "click", "intensity": 50, "duration": 800, "message": "boop" }
{ "type": "message", "message": "good puppy" }
{ "type": "osc", "subtype": "Vibrate", "intensity": 30, "duration": 1000 }
{ "type": "rest", "id": "cfg_abc", "variables": { "speed": 3 }, "message": "hi" }
{ "type": "integration", "id": "btn_abc", "params": { "addSeconds": 600 } }

Success response:

{ "success": true, "dndSuppressed": false, "message": "…" }

• dndSuppressed is present on click, message, osc, rest, and integration results. It's true only when the puppy is in Do Not Disturb and shares their DND status; otherwise it's always false (their private DND state is never leaked to you). See Behaviour and semantics.
• message echoes any response text the upstream REST or integration returned; absent for plain clicks and messages.

curl -X POST \
  -H "Authorization: Bearer pak_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"click","message":"boop"}' \
  https://puppyclicker-api.boundfire.com/api/v2/puppies/<puppyId>/actions

Failure modes worth handling: 404 PUPPY_NOT_FOUND (not your friend), 400 TARGET_NOT_CONFIGURED (for example osc to a puppy with no device), 404 ACTION_NOT_FOUND (bad, inactive, or non-delegated rest/integration id), 502 UPSTREAM_FAILED (their device or webhook errored, but the click is still recorded), 429 RATE_LIMITED.

GET /clicks/received

Cursor-paginated feed of clicks you received, newest first. Costs 1 read.

Query params:

{
  "items": [
    {
      "id": "clk_…",
      "type": "click",
      "source": null,
      "message": "boop",
      "intensity": null,
      "duration": null,
      "timestamp": "2026-07-13T12:00:00.000Z",
      "senderId": "usr_…",
      "senderUsername": "owner",
      "senderPoundUsername": null,
      "hidden": false
    }
  ],
  "nextCursor": "2026-07-13T12:00:00.000Z_clk_…"
}

• type is the click kind: click, zap (OpenShock), api (API / REST / integration / self), and so on.
• source is where it originated (null for a direct friend click, or values like pound / landing for social and landing-page clicks).
• hidden: true rows come from a user you've blocked or who blocked you. Their senderId / senderUsername / senderPoundUsername are null, but the click itself is still listed.
• nextCursor is null when there are no more rows. To page, pass it back verbatim as cursor.

POST /clicks/self

v1-click parity: records a self-click and rings your own devices. Consumes 1 action.

Body (optional):

{ "message": "optional, up to 150 chars" }

Response:

{ "success": true, "dndSuppressed": false }

Here dndSuppressed reflects your own DND state (the recipient is you, so it's not a privacy leak): true means your quiet hours suppressed the push, though the click was still recorded and streamed.

curl -X POST -H "Authorization: Bearer pak_..." \
  -H "Content-Type: application/json" -d '{"message":"coffee"}' \
  https://puppyclicker-api.boundfire.com/api/v2/clicks/self

This is the v2 equivalent of GET /api/v1/click: same effect. V1 will continue to be supported in perpetutity though.

GET /stream

A Server-Sent Events stream of your real-time alerts. These are the same events the desktop app receives (incoming clicks, messages, self-clicks, Pound social events), each with dndSuppressed flags. Does not consume the read budget; instead it's governed by the per-account concurrent-connection cap.

Auth accepts either the bearer header or ?key= (the latter for browser EventSource, which can't set headers):

# In a browser you'd use EventSource("…/api/v2/stream?key=pak_…").
# From a shell with a header:
curl -N -H "Authorization: Bearer pak_..." \
  https://puppyclicker-api.boundfire.com/api/v2/stream

# Or with the query key:
curl -N "https://puppyclicker-api.boundfire.com/api/v2/stream?key=pak_..."

Frame types on the wire:

1. ready, sent once on connect:

   event: ready
   data: {"connectedAt":"2026-07-13T12:00:00.000Z"}

2. Keepalive comments every 25 seconds (SSE comment lines, ignore them):

   : keepalive

3. alert events, your actual notifications:

   event: alert
   data: {"id":"clk_…","kind":"click","senderUsername":"owner","body":"boop","timestamp":"2026-07-13T12:00:00.000Z","dndSuppressed":false}

Alert data fields (all additive, so ignore unknown keys):

Concurrency is capped per account (1 free / 5 supporter); over-cap connects get 429 STREAM_LIMIT. Reconnect with exponential backoff.