Agent API

A single endpoint for cards and current-period reward status, designed for agents and automations. The API pulls your encrypted cloud sync backup, decrypts it in memory, and recomputes rewards with your YNAB PAT. Nothing is stored server-side.

Quick start

1. In Settings, enable Cloud Sync and keep the 12-word code.

2. Create or copy a YNAB Personal Access Token.

3. Call /api/agent/rewards with both values.

Tip: amounts are returned in dollars, not milliunits. Add transactions to get card recommendations for specific purchases.

Security model

Cloud Sync stores only encrypted data. This API decrypts the payload in memory and discards it after the response is sent.

Your PAT and sync code are never stored. Each call is self-contained and stateless.

Request

POST /api/agent/rewards

Send JSON in the body. Headers are optional if you prefer to keep secrets out of the payload.

curl -X POST https://your-domain.example/api/agent/rewards \
  -H "Content-Type: application/json" \
  -d '{
    "pat": "<YNAB_PAT>",
    "syncCode": "twelve word cloud sync phrase",
    "includeBreakdowns": false
  }'
curl -X POST https://your-domain.example/api/agent/rewards \
  -H "Content-Type: application/json" \
  -d '{
    "pat": "<YNAB_PAT>",
    "syncCode": "twelve word cloud sync phrase",
    "include": ["cards", "signals", "advice"],
    "cardsView": "limits",
    "transactions": [
      { "id": "txn-1", "amount": 82.5, "themeGroupName": "Groceries" },
      { "id": "txn-2", "amount": 120, "flagColor": "blue" }
    ]
  }'

Optional headers

Authorization: Bearer <YNAB_PAT>

X-Cloud-Sync-Code: <sync code>

X-YNAB-PAT: <YNAB_PAT>

pat

Required. Your YNAB Personal Access Token.

syncCode

Required. The 12-word Cloud Sync code that decrypts your backup.

budgetId

Optional. Overrides the budget stored in your Cloud Sync backup.

includeBreakdowns

Optional. Include category and subcategory breakdowns on each rule.

cardIds

Optional. Restrict the response to specific card IDs.

include

Optional. Limit sections in the response. Supported values:cards, signals, categories, advice, alerts. Defaults to all.

cardsView

Optional. Use limits for a slim card payload (only limits and status) or full for detailed spend and rule breakdowns. Defaults to full.

transactions

Optional. Provide an array of transactions to get a ranked card recommendation per transaction. Use either themeGroupId/themeGroupName or flagColor for each entry.

Response

The response includes a top-level summary plus per-card reward status. Each card contains a status summary and a per-rule breakdown.

Category recommendations are generated from your theme groups, and transaction advice is returned only when you send transactions.

Use include and cardsView to reduce response size for agent queries.

{
  "meta": {
    "generatedAt": "2026-02-03T10:12:00.000Z",
    "budgetId": "...",
    "budgetName": "Household",
    "calculationSource": "fresh",
    "cloudSyncUpdatedAt": "2026-02-03T09:59:12.000Z",
    "cardsCount": 4,
    "rulesCount": 7
  },
  "settings": {
    "currency": "USD",
    "milesValuation": 0.01
  },
  "signals": {
    "minimumSpendNeeded": [
      { "cardId": "card-2", "cardName": "Travel Miles", "remaining": 120.5, "scope": "card" }
    ],
    "maximumSpendHeadroom": [
      { "cardId": "card-1", "cardName": "Everyday Cashback", "remaining": 250, "cap": 1500, "progress": 83.3 }
    ],
    "maximumSpendReached": []
  },
  "cards": [
    {
      "id": "card-1",
      "name": "Everyday Cashback",
      "issuer": "Example Bank",
      "type": "cashback",
      "status": {
        "available": true,
        "period": "2026-02",
        "spend": {
          "total": 812.34,
          "eligible": 812.34,
          "eligibleBeforeBlocks": 812.34,
          "rewardEarned": 24.37,
          "rewardEarnedDollars": 24.37,
          "rewardType": "cashback"
        },
        "limits": {
          "minimum": { "target": null, "remaining": null, "progress": null, "met": null },
          "maximum": { "cap": 1500, "remaining": 687.66, "progress": 54.2, "exceeded": false },
          "shouldStopUsing": false
        },
        "rules": [
          {
            "ruleId": "rule-1",
            "ruleName": "Base rate",
            "period": "2026-02",
            "rewardType": "cashback",
            "totalSpend": 812.34,
            "eligibleSpend": 812.34,
            "minimumTarget": null,
            "minimumRemaining": null,
            "maximumCap": null,
            "maximumRemaining": null
          }
        ]
      },
      "recommendation": {
        "cardId": "card-1",
        "cardName": "Everyday Cashback",
        "reason": "Good reward rate (3.0%)",
        "priority": "medium",
        "action": "use"
      }
    }
  ],
  "transactionAdvice": [
    {
      "id": "txn-1",
      "amount": 82.5,
      "method": "theme_group",
      "group": { "id": "group-1", "name": "Groceries" },
      "recommended": {
        "cardId": "card-1",
        "cardName": "Everyday Cashback",
        "status": "use",
        "rewardRate": 0.03,
        "reasons": ["Reward rate 3.00%", "687.66 dollars headroom to max"]
      },
      "ranked": []
    }
  ],
  "categories": [],
  "alerts": []
}

Status reasons when no calculations are available: missing_ynab_account,no_active_rules, or no_calculations.

Common errors: 401 for an invalid PAT or sync code, 404 if no cloud backup exists, and 429 when YNAB rate limits.

Transaction advice errors: invalid_amount, theme_group_not_found, or missing_theme_group_or_flag_color.

Response headers include X-Agent-Api-Include and X-Agent-Api-Cards-View for quick inspection.