> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding your financial data

> Reference for Yoshi resources: accounts, transactions, scores, recurring streams, goals, income, and investments, plus key fields and relationships.

Yoshi organizes your financial data into a set of core resources. This page explains what each one represents and how to interpret key fields.

## Accounts

An account represents a single financial account — a checking account, savings account, credit card, investment account, or loan. Each account belongs to a financial institution and has a current balance.

| Field               | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `type`              | Top-level category: `depository`, `credit`, `investment`, `loan`              |
| `subtype`           | More specific: `checking`, `savings`, `credit card`, `401k`, `mortgage`, etc. |
| `balance_current`   | Most recent balance as reported by the institution                            |
| `balance_available` | Available to spend or withdraw (may differ from current for credit/checking)  |
| `balance_limit`     | Credit limit (credit accounts only)                                           |
| `as_of`             | When the balance was last refreshed                                           |
| `hidden`            | Whether the user has hidden this account from their dashboard                 |

<Info>
  `balance_available` may be `null` for accounts that don't report available balances, such as some investment accounts.
</Info>

## Transactions

A transaction is a single financial event — a purchase, payment, deposit, transfer, or fee. Transactions belong to an account and include merchant information, categorization, and timing data.

### Amount and direction

| Field                 | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| `amount`              | Signed amount. Negative for outflows, positive for inflows.      |
| `amount_absolute`     | Unsigned amount (always positive). Use this for display.         |
| `cash_flow_direction` | `"outflow"` (you spent money) or `"inflow"` (you received money) |

<Warning>
  The sign of `amount` follows accounting convention — a credit card purchase appears as a positive value on a credit account but as an outflow in `cash_flow_direction`. Always use `cash_flow_direction` for logic and `amount_absolute` for display.
</Warning>

### Dates

| Field             | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `date_posted`     | When the transaction settled (final). Use this for reporting. |
| `date_authorized` | When the transaction was first authorized. May be `null`.     |
| `pending`         | `true` if the transaction hasn't settled yet                  |

Pending transactions may change amount, date, or disappear entirely before posting. Use the transaction `id` for deduplication — don't match on amount or description.

### Categories

| Field            | Description                                    |
| ---------------- | ---------------------------------------------- |
| `category_label` | Human-readable label, e.g. "Groceries"         |
| `category_tier1` | Top-level category, e.g. "Food & Drink"        |
| `category_tier2` | Sub-category, e.g. "Groceries". May be `null`. |

### Merchant

| Field                   | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `counterparty_name`     | Cleaned merchant name, e.g. "Whole Foods"        |
| `counterparty_logo_url` | Merchant logo URL. May be `null`.                |
| `original_description`  | Raw transaction description from the institution |

## Recurring streams

A recurring stream is a detected pattern of repeated transactions — subscriptions, monthly bills, or regular income. Yoshi identifies these automatically from transaction history.

| Field                 | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| `direction`           | `"outflow"` (bill/subscription) or `"inflow"` (income)            |
| `frequency`           | Detected pattern: `monthly`, `weekly`, `biweekly`, `annual`, etc. |
| `status`              | `"active"` or `"inactive"` (stream appears to have stopped)       |
| `average_amount`      | Typical amount based on recent occurrences                        |
| `predicted_next_date` | When the next occurrence is expected                              |

## Scores

Yoshi calculates four financial health scores, each on a 0–100 scale:

| Score      | What it measures                                     |
| ---------- | ---------------------------------------------------- |
| `yoshi`    | Composite overall financial health                   |
| `recovery` | How quickly you recover from spending dips           |
| `capacity` | Available financial cushion relative to obligations  |
| `baseline` | Consistency and stability of your financial patterns |

Scores are recalculated daily. The `observation_date` field indicates when the scores were last computed.

## Goals

A goal represents a financial objective the user is working toward:

| Field           | Description                                       |
| --------------- | ------------------------------------------------- |
| `goal_type`     | What kind of goal: `savings`, `debt_payoff`, etc. |
| `status`        | `active`, `paused`, or `completed`                |
| `target_amount` | Dollar amount the user is trying to reach         |
| `current_value` | Progress toward the target                        |
| `target_date`   | When the user wants to reach the goal             |

## Income

The income resource provides an analysis of the user's income sources:

| Field                         | Description                                                 |
| ----------------------------- | ----------------------------------------------------------- |
| `total_income_annual`         | Estimated annual income across all sources                  |
| `total_income_monthly`        | Estimated monthly income                                    |
| `income_sources`              | Array of detected income streams                            |
| `income_sources[].confidence` | `high`, `medium`, or `low` — how confident the detection is |

## Investments

Investment data shows the user's holdings grouped by asset class:

| Field                | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `symbol`             | Ticker symbol, e.g. "AAPL"                            |
| `current_value`      | Market value of the position                          |
| `quantity`           | Number of shares held                                 |
| `cost_basis_total`   | Original purchase cost                                |
| `total_gain_loss`    | Unrealized gain or loss                               |
| `day_change`         | Change in value today                                 |
| `percent_of_account` | Position as a percentage of the total account (0–100) |

## Resource relationships

```
User
├── Accounts
│   ├── Transactions
│   └── Balance history
├── Recurring streams
├── Scores
├── Goals
├── Income sources
└── Investments (holdings by account)
```

Every resource is scoped to the authenticated user. You can only access your own data — there is no cross-user access.