YNAB API - Grab Your Budget Data Programmatically

YNAB's API launched in June 2018. It's a REST API that spits out JSON - standard stuff if you've used any API before. Base URL is https://api.ynab.com/v1 and everything comes back wrapped in a data object. The team documented how they use OpenAPI/Swagger to build their interactive docs, which is why their API documentation actually works.

Personal Tokens vs OAuth

Personal tokens are way easier for personal projects. Go to your YNAB settings, generate a token, done. Never expires unless you revoke it. Perfect for automating your own budget or pulling reports.

OAuth is required if you're building an app for other people. Standard OAuth 2.0 flow - nothing weird here. You start in "restricted mode" (25 users max) until YNAB manually approves your app. Takes a few days typically. The starter kit shows how OAuth works if you need examples.

Use personal tokens unless you hate yourself and want to deal with OAuth. Way easier - the setup is 5 minutes vs 2 hours.

What Actually Works

The API hits the main YNAB features you actually care about: Budgets - list them, get metadata, the usual stuff. Accounts - balances, transactions, everything you'd expect. Categories - read budgeted amounts, modify them (this is where it gets useful). Transactions - create, update, delete, full CRUD on everything. Payees - manage who you pay money to. All the endpoints are documented if you want the full reference.

Delta sync saves your ass - only returns what changed since your last request. Saves bandwidth and makes everything faster. Learned this when I was hitting rate limits every 10 minutes debugging transaction imports - switched to delta requests and suddenly my problems went away. The OpenAPI specification includes all the technical details if you need to generate your own client.

Rate Limits and Gotchas

200 requests per hour in a rolling window. Hit the limit, get a 429 error, wait it out. The limit is fine for most personal projects - I've never hit it building automation scripts. But if you're polling every 5 minutes, you'll run into trouble. The official rate limiting docs explain how to check your remaining requests in response headers.

Pro tip: Cache responses and use delta requests. Don't be the person fetching all transactions every time when you only need the new ones.

Milliunits confused the shit out of me for like a week: $100.50 becomes 100500 milliunits. Why? Because JavaScript's floating point math is garbage and YNAB didn't want transaction amounts to randomly change by a penny. More details here.

Error handling is pretty good - actual useful messages instead of generic 500s. The API docs are solid too, with interactive examples you can test right in your browser. For more context on the API design decisions, check out YNAB's support overview which explains the philosophy behind their developer tools.

5-Minute Setup (Actually This Time)

1. Go to YNAB settings
2. Click "New Token", enter your password
3. Copy the token somewhere safe (you can't see it again)
4. Test your token with this curl command (replace YOUR_TOKEN with your actual token):

## Replace YOUR_TOKEN with your real token from step 3
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.ynab.com/v1/budgets"

Success means JSON with your budgets. A 401 means your token is wrong. You can also test using the interactive API explorer in your browser which handles authentication for you.

SDKs That Actually Work

The official SDKs actually work - don't reinvent the wheel:

JavaScript (npm): Works in browsers and Node. The starter kit is worth looking at if you need OAuth examples. TypeScript definitions included.

Ruby (gem): Clean API, handles auth headers automatically. Better than the community alternatives.

Python (PyPI): Official library that finally replaces the janky community versions. Works with Python 3.8+.

For other languages, community SDKs exist but they're hit-or-miss quality-wise.

Milliunits Will Break Your Brain

Every dollar amount is multiplied by 1000. $50.00 = 50000 milliunits. $0.01 = 10 milliunits.

This confused the absolute hell out of me when I first started. I kept thinking my transactions were showing amounts 1000x too large. The API docs explain why - it's because JavaScript math with decimals is garbage and YNAB didn't want transaction amounts to randomly drift by a penny due to floating point errors.

// Wrong
const amount = 50.00;

// Right  
const amount = 50000; // $50.00 in milliunits

Real-World Gotchas I've Hit

Error 429 during development: The 200/hour limit hits fast when you're debugging. Cache your responses or you'll be sitting there waiting.

Subscription lapses: If someone's YNAB subscription expires, you get 403s immediately. Handle this gracefully or users will think your app is broken.

Date format strictness: Use ISO format (YYYY-MM-DD) or transactions fail silently. date-fns handles this better than Moment.js (which is deprecated now). Learned this the hard way when half my imports randomly failed.

Category deletion: You can't delete categories through the API. Had to tell users to do it manually in YNAB, then sync. Fucking annoying.

Production nightmare I had: Deployed to production and realized all transaction amounts were showing 1000x too large because I forgot to convert from milliunits. Took down the app for 2 hours while I fixed it at 3am. Always test your milliunit conversions.

Community Tools Worth Using

The Works with YNAB showcase has 30+ apps, but most are abandoned projects or demos. These actually work:

• Sync for YNAB: European bank import. Saves you from scraping bank websites.
• Bank2YNAB: CSV conversion tool for US banks. Open source.
• Toolkit for YNAB: Browser extension that adds features YNAB should have built.

Debug Like a Pro

Turn on request logging in whatever HTTP client you're using. YNAB's error messages are actually helpful:

{
  "error": {
    "id": "400.1", 
    "name": "invalid_request",
    "description": "Budget not found"
  }
}

Way better than generic 400s. The status page shows if the API is having issues.

Pro tip: Use the browser dev tools on api.ynab.com/v1 to test calls interactively. Built-in Swagger UI that actually works.