BAD developer docs

BAD is not another wearable. It's the intelligence layer — the unified health graph — that sits above every wearable, lab, and health source and fuses them into one cross-source picture and one answer: “am I getting healthier, and what should I do this week?”

The API, MCP server, and badstackexist so any agent can read & write that one unified graph programmatically — activities, recovery, labs, nutrition, and body composition, merged best-of-source across providers rather than siloed per app.

Today the graph is populated by Apple Health (including Apple Watch via HealthKit) and Strava. It's designed to absorb every other source the same way — via OAuth/API adapters where they exist, or raw uploads (lab PDFs, DEXA reports, device screenshots) where they don't — each new source landing in the same canonical layers. Recovery wearables (Whoop, Oura, Garmin), biomarkers (Superpower, Function Health, TruDiagnostic), and body composition (DEXA, VO₂max) are on the roadmap via that adapter / upload pattern; they are not live yet.

Every request authenticates with a Bearer token. Grab a developer API key (it starts with bad_sk_) from Settings → API — that screen also hands you a ready-to-paste setup prompt for your agent. Then export it and make a call.

export BAD_API_KEY="bad_sk_..."

# Verify the key — fetch your profile
curl "https://bad.app/api/v1/me" -H "Authorization: Bearer $BAD_API_KEY"

One-curl install (badstack)

The fastest path: install the badstack onto any local agent. It pulls down the skills + MCP wiring and keeps itself updated.

curl -fsSL https://bad.app/api/badstack/install | BAD_API_KEY=bad_sk_… sh

badstack is a gstack-style skill and tool stack for any local coding/agent runtime. One install command drops in a curated set of BAD skills (slash commands, prompts) plus the MCP server wiring, so your agent immediately knows how to read your training data, log workouts and meals, pull your digest, and update your plan — without you hand-wiring anything.

• Auto-updating — the stack refreshes its skills + tool definitions in the background, so new BAD tools show up without a re-install.
• Agent-agnostic — works with Claude Code, Cursor, Codex, and any MCP-capable client.
• Key-scoped — everything runs against your bad_sk_ key, so it only ever touches your own account.

Your Settings → API screen gives you both the key and a copy-paste prompt that tells your agent how to use the stack.

The BAD MCP server is plain Streamable HTTP at https://bad.app/api/mcp. Authenticate with the same bad_sk_ key via the Authorization header. Pick your agent below.

Claude Code

claude mcp add --transport http bad https://bad.app/api/mcp \
  --header "Authorization: Bearer $BAD_API_KEY"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bad": {
      "url": "https://bad.app/api/mcp",
      "headers": {
        "Authorization": "Bearer bad_sk_..."
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.bad]
url = "https://bad.app/api/mcp"

[mcp_servers.bad.headers]
Authorization = "Bearer bad_sk_..."

Generic MCP client (Pi.dev / Hermes / OpenClaw / any)

Any MCP client that speaks Streamable HTTP can use this shape:

{
  "mcpServers": {
    "bad": {
      "type": "http",
      "url": "https://bad.app/api/mcp",
      "headers": {
        "Authorization": "Bearer bad_sk_..."
      }
    }
  }
}

Both the REST API and the MCP server authenticate with a single header: Authorization: Bearer <token>. Two credential types are accepted:

• Developer API key — starts with bad_sk_. Created in Settings → API. This is what agents and the badstack use.
• Session token — issued to the web and iOS apps at login. Also works as a Bearer credential.

Keys are scoped to one athlete account with full read/write access. Only a SHA-256 hash and a short display prefix are stored server-side — the plaintext key is shown once, at creation. Keep it out of client-side code, and revoke it from Settings if it leaks.

{ "error": { "code": "ERROR", "message": "Invalid or revoked API key" } }

Every tool the BAD MCP server exposes. The user id is taken from your Bearer credential — you never pass it. * = required.

List them live at any time:

curl "https://bad.app/api/mcp" -X POST \
  -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

All endpoints live under https://bad.app/api/v1, return JSON, and (except the auth endpoints) require the Bearer header. Grouped logically below.

Responses are canonical — one record per real-world event/day/marker, merged best-of-source across every connected provider — so reads like /timeline and /activities/detail are richer than any single source and expose which sources contributed.

curl "https://bad.app/api/v1/timeline?limit=200" \
  -H "Authorization: Bearer $BAD_API_KEY"

curl "https://bad.app/api/v1/daily-logs" \
  -X PATCH -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "weight_in": 178.2, "habits": { "keto": true, "core_score": 4 } }'

curl "https://bad.app/api/v1/nutrition" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "2 eggs + oatmeal", "calories": 420, "protein": 24 }'

curl "https://bad.app/api/v1/body-fat" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "biologicalSex": "male", "heightInches": 70, "neckInches": 15, "waistInches": 34, "weightLbs": 175 }'

curl "https://bad.app/api/v1/labs" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "Total Cholesterol", "value": 168, "unit": "mg/dL", "category": "Lipids" }'

curl "https://bad.app/api/v1/chat" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" --no-buffer \
  -d '{ "message": "How should I pace my long run Sunday?" }'

curl "https://bad.app/api/v1/feed" \
  -H "Authorization: Bearer $BAD_API_KEY"

curl "https://bad.app/api/v1/me" \
  -H "Authorization: Bearer $BAD_API_KEY"

curl "https://bad.app/api/v1/screenshot" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image": "data:image/png;base64,..." }'

curl "https://bad.app/api/v1/keys" \
  -X POST -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Claude Code" }'

curl "https://bad.app/api/v1/auth/login" \
  -X POST -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "•••" }'

cURL

# Log a meal, then read today's macro totals
curl "https://bad.app/api/v1/nutrition" -X POST \
  -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "grilled chicken + rice", "calories": 560, "protein": 48 }'

curl "https://bad.app/api/v1/nutrition" -H "Authorization: Bearer $BAD_API_KEY"

JavaScript (fetch)

const BASE = 'https://bad.app/api/v1'
const headers = {
  Authorization: `Bearer ${process.env.BAD_API_KEY}`,
  'Content-Type': 'application/json',
}

// Read the unified timeline
const res = await fetch(`${BASE}/timeline?limit=50`, { headers })
if (!res.ok) throw new Error(await res.text())
const { activities, heatmap, counts } = await res.json()
console.log(counts, activities.length)

MCP tools/call (JSON-RPC)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "log_meal",
    "arguments": {
      "description": "2 eggs + oatmeal",
      "calories": 420,
      "protein": 24
    }
  }
}

Over HTTP, that's a single POST to the MCP endpoint:

curl "https://bad.app/api/mcp" -X POST \
  -H "Authorization: Bearer $BAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"get_training_digest","arguments":{}}}'

Paste this into your agent's system prompt or a project instruction file once the BAD MCP server is connected. (Settings → API generates a personalized version too.)

You have access to the BAD MCP server (the user's training + health data).
Use it proactively:

- Before advising on training, call get_training_digest and get_timeline to
  ground yourself in real data.
- When the user reports a workout, meal, weight, or how they feel, log it:
  log_activity / log_meal / log_weight / log_checkin / log_recovery.
- For nutrition or body-composition questions, read get_nutrition, get_body_fat,
  get_measurements, and get_labs first.
- Use get_consistency to gauge adherence before pushing or easing off.
- When you learn a durable fact about the user (injury, preference, goal),
  call remember so future sessions keep it.

Never ask the user for their user id — it comes from the API key. Prefer
get_timeline over get_activities for cross-source history.