Developers
Your almanac has a REST API, an MCP server for Claude and other AI assistants, and a command-line tool. All three read and change the same almanac you see on the site, with the same rules.
- API base
- https://yourbodyalmanac.com/api/v1
- MCP server
- https://yourbodyalmanac.com/mcp
- CLI
- npx yourbodyalmanac
- Format
- JSON
Not medical advice, in your app either. Everything here is general information. If you build on it, say so where your users will see it: each Today response carries a disclaimer you can show as-is. Link to our disclaimer, and don't present practices as diagnosis or treatment. The API, MCP server and CLI are operated by AKDARRAH LLC and covered by the same Terms of use; questions to hello@akdarrah.com.
Part I
Authentication
Every request carries a bearer token. There are two kinds, and the API treats them the same: a token acts as you, with your account's Premium status.
| Kind | Best for | How to get one |
|---|---|---|
| Personal access token | Your own scripts and the yba command line | Create one on API & apps. It starts yba_ and is shown once. Revoke it there any time. |
| OAuth 2.1 | Apps that act for someone else, including Claude connectors | Authorization code with PKCE at /oauth/authorize and /oauth/token; revoke at /oauth/revoke. One scope, almanac. Clients can register themselves at /oauth/register and discover it all at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. |
$ curl https://yourbodyalmanac.com/api/v1/me \ -H "Authorization: Bearer yba_your_token_here"The almanac scope covers everything below: read and update your factors, habits, Today, progress and settings. Deleting an account also needs the account's email address in the request.
Part II
REST API
Paths are relative to https://yourbodyalmanac.com/api/v1. Send and receive JSON. Factor slugs and practice keys are the ones in the site's URLs, like office-worker and hip-flexor-stretch.
Content, your account and settings, and /export work on every account. Your almanac and habits, marked Premium, need Premium on the API, MCP and CLI (free during the beta); without it they answer 403. On the website the daily loop is free: Today, up to three habits, stamps and the last 30 days of Progress.
| Method | Path | What it does |
|---|---|---|
| Content | ||
| GET | /categories | The categories factors are filed under, like occupations and hobbies. |
| GET | /factors?q=&category= | Search or browse factors. |
| GET | /factors/:slug | One factor: what it takes, what to do, and sources. |
| GET | /practices?frequency= | Every practice, with how often and how long. |
| GET | /practices/:key | One practice: steps, why it helps, cautions and sources. |
| Your account | ||
| GET | /me | Your account: time zone, Premium, email and phone notification settings, and the place Today reads the sky for. |
| PATCH | /me | Change time_zone, morning_email, morning_hour (4–11), evening_email, evening_hour (16–23), or push_morning / push_evening for phone notifications. weekly_email and push_weekly turn the Sunday weekly review on or off (Premium). place takes a US ZIP code or "City, ST" and is looked up on the spot (a 422 if it can't be found); an empty string clears it, and the forecast falls back to the capital of the state in your almanac. We never use a device's location. |
| DELETE | /me?confirm=<email> | Delete your account and all its data. Needs your email address to confirm, and a personal access token: OAuth apps get a 403. |
| GET | /export?format=json|csv | Everything you've saved, to keep: factors, habits (every stint), checks (every stamp with stamped_at), occasions and meals. format=csv answers text/csv, one row per record. Free on every plan. |
| Your almanac Premium | ||
| GET | /almanac/factors | The factors you've saved. |
| POST | /almanac/factors | Save a factor by slug, like {"slug": "nurse"}. |
| DELETE | /almanac/factors/:slug | Remove a factor. |
| GET | /suggestions?starter=1 | Practices your factors suggest, why, and whether you track each one. starter=1 gives the three to start with. |
| POST | /suggestions/snooze | “Not now” on the one-more-habit offer (next_suggestion in /today, shown after a 7-day streak). It comes back in a week. |
| GET | /habits | The habits you track, with streaks. |
| POST | /habits | Track a suggestion by key, like {"key": "hip-flexor-stretch"}, or add your own with title and frequency, like {"title": "Read 20 pages", "frequency": "weekly"}. |
| POST | /habits/track_all | Track every suggestion at once. |
| DELETE | /habits/:key | Stop tracking a habit. Its history stays. |
| Today Premium | ||
| GET | /today | Today's edition: daily, weekly and “Today I…” items; edition (morning or night); place, sky and forecast, the readings for your body with their tips (available: false when the forecast can't be fetched, null with no place); moon; streak, with this week's rest day (one missed day a week keeps it); learn, a fact from your almanac; and milestone on the day you reach 7, 30 or 100. |
| PUT | /today/checks/:key | Tick a habit off. |
| DELETE | /today/checks/:key | Untick it. |
| PUT | /today/occasions/:slug | Log “Today I…”, like drinking-alcohol. Its practices join today's list. |
| DELETE | /today/occasions/:slug | Take it back. |
| Progress and review Premium | ||
| GET | /progress?month=2026-10 | A month of days done, plus each habit's current and best streak. |
| GET | /review?week=2026-10-25 | The weekly review for a Sunday-to-Saturday week (the last complete one by default): kept days of 7 and the rest_day; days with each one's state and moon; habits, each with seven marks (on, off, or na on days a weekly habit wasn't due); steadiest and slipped; occasions with counts; note, one sentence on timing drawn from your stamps; and this_week. |
| Meals Premium | ||
| GET | /meals?date=2026-10-28 | A day's meals (today by default): each with calories, source (estimate or given) and Claude's note on what it assumed; the day's total; and week, the seven days up to it. Calories are estimates, not measurements. |
| POST | /meals | Log a meal or snack: description in your words (up to 500 characters) and, if you know it, calories (0–10000). Without calories, Claude estimates them; only the description is sent. Answers 201 with the meal and the day. A 503 means the estimate didn't come back (send the calories, or retry); a 429 means the day's 30 estimates are used, and a number you give still logs. |
| PATCH | /meals/:id | Change the calories; the meal becomes your number. |
| DELETE | /meals/:id | Remove a meal. |
Example: today's checklist
$ curl https://yourbodyalmanac.com/api/v1/today \ -H "Authorization: Bearer yba_your_token_here"{ "today": { "date": "2026-10-27", "done": 6, "total": 14, "days_in_a_row": 12, "edition": "morning", "day_kept": false, "place": { "name": "Indianapolis, IN", "source": "place", "state": null }, "moon": { "phase": "Waning gibbous", "percent_lit": 82 }, "forecast": { "available": true, "summary": "A frosty start.", "readings": [ { "key": "low", "label": "Low this morning", "figure": "31°F", "qualifier": "High 54°F", "tip": "Layers for an early walk." }, { "key": "uv", "label": "UV index", "figure": "3", "qualifier": "Moderate", "tip": null, "note": "Peaks around midday." } ] }, "streak": { "days": 12, "today_kept": false, "rest_day_used_this_week": true, "rest_days": ["2026-10-25"], "next_rest_day_opens": "2026-11-01" }, "learn": { "factor": "indiana", "title": "Weak winter sun and vitamin D", "sentence": "…" }, "milestone": null, "daily": [ { "key": "hip-flexor-stretch", "title": "Stretch your hip flexors", "frequency": "daily", "own": false, "practice": "hip-flexor-stretch", "started_on": "2026-10-12", "streak": 12, "done": true } ], "weekly": [ { "key": "strength-training", "title": "Strength-train twice a week", "streak": 5, "done": true } ], "occasions_available": [ { "slug": "drinking-alcohol", "label": "Drank alcohol", "logged": true } ], "occasions": [ { "slug": "drinking-alcohol", "label": "Drank alcohol", "practices": [ { "key": "alternate-water-with-alcohol", "title": "Alternate alcohol with water", "done": false } ] } ], "disclaimer": "General information, not medical advice. Talk to a doctor before changing your diet, supplements or exercise." }}Part III
MCP
The MCP server lets Claude and other AI assistants read your almanac and tick things off for you. It speaks streamable HTTP, signs people in with OAuth, and follows the same rules as the API: content, account, settings and export tools work on every account; the almanac and habit tools, marked Premium, need Premium. Every tool's description repeats the not-medical-advice line.
Claude on the web
In claude.ai, add a custom connector with this URL, then sign in here and choose Allow.
https://yourbodyalmanac.com/mcpClaude Code
Run this once. Claude Code opens a browser for you to sign in.
$ claude mcp add --transport http almanac https://yourbodyalmanac.com/mcp| Tool | What it does |
|---|---|
| Content | |
| search_factors | Search or browse factors, optionally in one category. |
| list_categories | The categories factors are filed under. |
| get_factor | One factor: what it takes, what to do, sources. |
| list_practices | Every practice. |
| get_practice | One practice: steps, why, cautions, sources. |
| Your account | |
| get_account | Your account, time zone, Premium and email settings. |
| update_settings | Change your time zone, email and notification settings (the weekly review too), or your place (a ZIP code or “City, ST”). |
| delete_account | Delete your account. Only with a personal access token (never over OAuth) and your email address typed back. |
| export_almanac | Everything you've saved, as JSON or (format: "csv") a spreadsheet. Free on every plan. |
| Your almanac Premium | |
| list_my_factors | The factors you've saved. |
| add_factor | Save a factor. |
| remove_factor | Remove a factor. |
| list_suggestions | Practices your factors suggest; starter: true for the three to start with. |
| snooze_next_suggestion | “Not now” on the one-more-habit offer. |
| list_habits | The habits you track, with streaks. |
| track_habit | Track a suggestion. |
| untrack_habit | Stop tracking a habit. |
| track_all_suggestions | Track every suggestion at once. |
| add_own_habit | Add a habit of your own, daily or weekly. |
| Today Premium | |
| get_today | Today's edition: the checklist, the forecast for your body, the moon, your streak and its rest day, a fact from your almanac and any milestone. |
| check_off | Tick a habit off. |
| uncheck | Untick it. |
| log_occasion | Log “Today I…”. |
| unlog_occasion | Take it back. |
| Progress and review Premium | |
| get_progress | A month of days done, and streaks. |
| get_weekly_review | The weekly review: days kept of 7 with the rest day, each habit's seven marks, steadiest and slipped, occasions, the almanac's note and the week ahead. week picks an earlier one. |
| Meals Premium | |
| list_meals | A day's meals, the total and the seven days up to it. date picks another day. |
| log_meal | Log what the user ate. Give calories when they know them; leave it out and Claude estimates them. |
| update_meal | Change a meal's calories to the user's number. |
| delete_meal | Remove a meal. |
Part IV
Command line
The yba command needs Node 18 or newer and nothing else. Install it with npm install -g yourbodyalmanac to get the yba command used below, or run any command without installing as npx yourbodyalmanac <command>.
Log in once with a token from API & apps; it's saved in ~/.config/yourbodyalmanac/config.json. You can set YBA_TOKEN (and YBA_HOST) instead. Add --json to any command for scripts.
$ npx yourbodyalmanac loginCreate a personal access token at https://yourbodyalmanac.com/almanac/apiToken:✓ Logged in to https://yourbodyalmanac.com as you@example.com| Command | What it does |
|---|---|
| Content | |
| yba search <words> [--category occupations] | Search factors. |
| yba categories | List the categories. |
| yba factor <slug> | Read a factor. |
| yba practices | List every practice. |
| yba practice <key> | Read a practice. |
| Your account | |
| yba me | Your account and settings. |
| yba settings set --evening-hour 21 | Change a setting. The others are --time-zone, --morning on|off, --morning-hour, --evening on|off, --push-morning on|off / --push-evening on|off for phone notifications, and --weekly on|off / --push-weekly on|off for the Sunday weekly review. |
| yba settings set --place 46204 | Where Today's forecast is for: a ZIP code or "Carmel, IN". --place "" goes back to your state. yba settings --place works too. |
| yba export [--format csv|json] > almanac.csv | Download everything you've saved. Free on every plan. |
| yba account delete --confirm you@example.com | Delete your account and data. |
| Your almanac Premium | |
| yba factors | The factors you've saved. |
| yba factors add <slug> | Save a factor. yba factors remove takes it out. |
| yba suggestions [--starter] | What your factors suggest, or the three to start with. |
| yba suggestions snooze | “Not now” on the one-more-habit offer. |
| yba habits | Your tracked habits. |
| yba habits track <key> | Track a suggestion. yba habits untrack stops. |
| yba habits add "Read 20 pages" [--weekly] | Add your own. --weekly for once a week. |
| yba habits track-all | Track every suggestion. |
| Today Premium | |
| yba today | Today's edition: the forecast for your body, your checklist, your streak and a fact from your almanac. |
| yba done <key> | Tick a habit off. yba undo unticks it. |
| yba did <slug> | Log “Today I…”. yba undid takes it back. |
| Progress and review Premium | |
| yba progress [--month 2026-10] | A month grid and your streaks. |
| yba review [--week 2026-10-25] | Last week read back: the moons, each habit's seven marks, steadiest and slipped, and the almanac's note. |
| Meals Premium | |
| yba ate "two eggs and toast" [--calories 420] | Log a meal or snack. Without --calories, Claude estimates them and says what it assumed. |
| yba meals [2026-10-28] | A day's meals with each one's id, calories and source, and the last seven days. |
| yba meals fix <id> <calories> | Change a meal's calories to your number. |
| yba meals remove <id> | Remove a meal. |
$ yba todayToday · Tuesday, October 27, 2026 6/14 done · 12 days in a rowMorning edition · Indianapolis, IN · Waning gibbous Forecast for your body: A frosty start. Low this morning 31°F (High 54°F) → Layers for an early walk. UV index 3 (Moderate) Peaks around midday. Every day [x] Stretch your hip flexors 12-day streak [x] Do glute bridges 12-day streak [ ] Follow the 20-20-20 rule 4-day streakThis week [x] Strength-train twice a week 5-week streakBecause you drank alcohol [ ] Alternate alcohol with water $ yba done 20-20-20-eye-ruleDone: Follow the 20-20-20 rule. 7 of 14 today. $ yba did drinking-alcoholLogged: Today I drank alcohol. 4 practices added to today.Part V
Errors
Errors come back as JSON with an error object: the HTTP status and a message written for a person to read, so an app or an assistant can pass it on as-is. The CLI prints it and exits non-zero.
| Status | When |
|---|---|
| 400 Bad request | A required parameter is missing. |
| 401 Unauthorized | No token, or it was revoked. Make a new one on API & apps, or sign in again. |
| 403 Forbidden | Needs Premium: the almanac and habit endpoints on a free account (“The API, MCP and command line for your almanac and habits come with Premium”), or a habit of your own. A fourth habit on the free almanac gets “The free almanac holds three habits…” too. |
| 404 Not found | No such factor, practice or habit, like Factor "office-workr" not found. |
| 422 Unprocessable | The request can't be done as sent, like month must look like 2026-10. |
| 429 Too many requests | More than 300 requests a minute. Wait a minute and try again. |
{ "error": { "status": 403, "message": "The API, MCP and command line for your almanac and habits come with Premium (free during the beta). Factors and practices stay open, and so does exporting your data. See https://yourbodyalmanac.com/upgrade" }}