Wallet API

https://rest.budgetbakers.com/wallet
Admin
Wallet API provides access to BudgetBakers Wallet records, accounts, budgets, and related financial...
Tokens:32,829
Snippets:116
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Goals

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of financial goals set by the user.

```APIDOC
## GET /v1/api/goals

### Description
Retrieves a list of financial goals set by the user.

### Method
GET

### Endpoint
/v1/api/goals

### Response
#### Success Response (200)
- **goals** (array) - A list of goal objects.

### Response Example
{
  "goals": [
    {
      "id": "goal_111",
      "name": "Save for Vacation",
      "target_amount": 3000.00,
      "current_amount": 1200.00,
      "currency": "USD"
    }
  ]
}
```

--------------------------------

### Get Labels

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of available labels for financial records.

```APIDOC
## GET /v1/api/labels

### Description
Retrieves a list of available labels for financial records.

### Method
GET

### Endpoint
/v1/api/labels

### Response
#### Success Response (200)
- **labels** (array) - A list of label objects.

### Response Example
{
  "labels": [
    {
      "id": "lbl_xyz",
      "name": "Urgent"
    }
  ]
}
```

--------------------------------

### Agent Hints: Enable Pagination Hints

Source: https://rest.budgetbakers.com/wallet/reference

Enable advisory information for AI agents by adding `agentHints=true` to any request. This example specifically enables pagination hints.

```http
agentHints=true
```

--------------------------------

### Get Financial Goals

Source: https://rest.budgetbakers.com/wallet/openapi

Returns a paginated list of financial goals. Supports filtering by various criteria and includes optional AI agent hints.

```APIDOC
## GET /v1/api/goals

### Description
Returns paginated list of financial goals. Default order: newest first (-createdAt).

### Method
GET

### Endpoint
/v1/api/goals

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions. (default: false)
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). (default: false)
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **name** (string) - Optional - Filter by name. Requires text prefix.
- **note** (string) - Optional - Filter goals by note. Requires text prefix.
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix.
- **updatedAt** (string) - Optional - Filter by last sync timestamp (when entity was last updated in the API database). Requires range prefix.

### Responses
#### Success Response (200)
- **(object)** - List of goals. Includes `PaginatedResponse` schema, `agentHints` array, and a `goals` array containing `Goal` objects.

#### Error Response (400)
- **(object)** - Bad Request - Invalid parameter value.
```

--------------------------------

### Get Categories

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of financial categories. Used for organizing financial records.

```APIDOC
## GET /v1/api/categories

### Description
Retrieves a list of financial categories. Used for organizing financial records.

### Method
GET

### Endpoint
/v1/api/categories

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects.

### Response Example
{
  "categories": [
    {
      "id": "cat_abc",
      "name": "Income",
      "parent_id": null
    },
    {
      "id": "cat_def",
      "name": "Groceries",
      "parent_id": "cat_ghi"
    }
  ]
}
```

--------------------------------

### GET /v1/api/standing-orders

Source: https://rest.budgetbakers.com/wallet/openapi

Returns a paginated list of recurring payments. The default order is newest first based on the creation date.

```APIDOC
## GET /v1/api/standing-orders

### Description
Returns paginated list of recurring payments. Default order: newest first (-createdAt).

### Method
GET

### Endpoint
/v1/api/standing-orders

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
```

--------------------------------

### Get Record Rules

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of predefined rules for automatically classifying financial records.

```APIDOC
## GET /v1/api/record-rules

### Description
Retrieves a list of predefined rules for automatically classifying financial records.

### Method
GET

### Endpoint
/v1/api/record-rules

### Response
#### Success Response (200)
- **record_rules** (array) - A list of record rule objects.

### Response Example
{
  "record_rules": [
    {
      "id": "rule_123",
      "description": "Auto-categorize 'Netflix' as Entertainment",
      "condition": {
        "field": "description",
        "operator": "contains-i",
        "value": "Netflix"
      },
      "action": {
        "field": "category_id",
        "value": "cat_ent"
      }
    }
  ]
}
```

--------------------------------

### Get Budgets

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of budgets. Supports filtering by date range and other criteria.

```APIDOC
## GET /v1/api/budgets

### Description
Retrieves a list of budgets. Supports filtering by date range and other criteria.

### Method
GET

### Endpoint
/v1/api/budgets

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Allows filtering budgets using specific prefixes and date ranges.

### Response
#### Success Response (200)
- **budgets** (array) - A list of budget objects.

### Response Example
{
  "budgets": [
    {
      "id": "bud_abc",
      "name": "Monthly Food Budget",
      "amount": 500.00,
      "currency": "USD",
      "period": "monthly"
    }
  ]
}
```

--------------------------------

### Get Entity References (Batch)

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves references for entities in a batch. Useful for checking dependencies before deletion.

```APIDOC
## GET /v1/api/{type}/references

### Description
Retrieves references for entities in a batch. Useful for checking dependencies before deletion.

### Method
GET

### Endpoint
/v1/api/{type}/references

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of entity for which to retrieve references (e.g., 'accounts', 'records').

#### Query Parameters
- **ids** (string) - Required - A comma-separated list of entity IDs for which to check references.

### Response
#### Success Response (200)
- **references** (object) - An object containing information about entity references.

### Response Example
{
  "references": {
    "acc_123": [
      {
        "type": "record",
        "id": "rec_789"
      }
    ]
  }
}
```

--------------------------------

### Get Labels

Source: https://rest.budgetbakers.com/wallet/openapi

Returns a paginated list of labels or hashtags. Supports filtering by various criteria and includes options for AI agent hints and total count.

```APIDOC
## GET /v1/api/labels

### Description
Returns paginated list of labels/hashtags. Default order: newest first (-createdAt). Supports filtering by various criteria and includes options for AI agent hints and total count.

### Method
GET

### Endpoint
/v1/api/labels

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions. (default: false)
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30). Example: "3f8e2a6b-9c4d-4e1f-b2a7-5d8c3e9f1a4b,7c2b9d4e-1f3a-4b5c-8e6d-2a7f9b3c1e5a"
- **name** (string) - Optional - Filter by name. Requires text prefix. Example: "eq.john"
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix. Example: "gte.2024-01-01T00:00:00Z"
- **updatedAt** (string) - Optional - Filter by last sync timestamp (when entity was last updated in the API database). Requires range prefix. Example: "gte.2024-01-01T00:00:00Z"
- **archived** (boolean) - Optional - Filter by archived status. true=archived only, false=active only, omit for all.
- **recordId** (string) - Optional - Filter labels used by a specific record.
- **budgetId** (string) - Optional - Filter items tracked by a specific budget.
- **standingOrderId** (string) - Optional - Filter labels used by a specific standing order.
- **recordRuleId** (string) - Optional - Filter labels used by a specific record rule.

### Request Example
(No request body specified in the source)

### Response
#### Success Response (200)
- **labels** (array) - List of labels.
- **agentHints** (array) - Structured hints for AI agents (if requested).
- **total** (integer) - Total count of matching items (if `withTotal` is true).

Headers:
- **X-Last-Data-Change-At** (string) - Timestamp of the last data change.
- **X-Last-Data-Change-Rev** (integer) - Revision number of the last data change.
- **X-RateLimit-Limit** (integer) - The maximum number of requests allowed in the current window.
- **X-RateLimit-Remaining** (integer) - The number of requests remaining in the current window.
- **X-Sync-In-Progress** (boolean) - Indicates if a sync operation is in progress.

#### Response Example
(No response example provided in the source)

ERROR HANDLING:
- 400: Bad Request - Invalid parameter value
- 401: Unauthorized
- 429: Rate limit exceeded. Check `Retry-After` header for when to retry.
```

--------------------------------

### Get Standing Orders

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of standing orders (recurring payments or transfers).

```APIDOC
## GET /v1/api/standing-orders

### Description
Retrieves a list of standing orders (recurring payments or transfers).

### Method
GET

### Endpoint
/v1/api/standing-orders

### Response
#### Success Response (200)
- **standing_orders** (array) - A list of standing order objects.

### Response Example
{
  "standing_orders": [
    {
      "id": "so_abc",
      "name": "Monthly Rent",
      "amount": 1200.00,
      "currency": "USD",
      "frequency": "monthly"
    }
  ]
}
```

--------------------------------

### Get Accounts

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of financial accounts. Supports filtering and sorting through query parameters.

```APIDOC
## GET /v1/api/accounts

### Description
Retrieves a list of financial accounts.

### Method
GET

### Endpoint
/v1/api/accounts

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Allows filtering results using specific prefixes like `eq.`, `contains.`, `gt.`, etc.
- **sort** (string) - Optional - Specifies the sorting order for the results.

### Response
#### Success Response (200)
- **accounts** (array) - A list of account objects.

### Response Example
{
  "accounts": [
    {
      "id": "acc_123",
      "name": "Checking Account",
      "currency": "USD",
      "balance": 1500.50
    }
  ]
}
```

--------------------------------

### Get Categories

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a paginated list of categories. Supports filtering by budget ID and sorting.

```APIDOC
## GET /categories

### Description
Retrieves a list of categories. This endpoint supports filtering by a specific budget ID and allows for sorting the results based on creation or update timestamps.

### Method
GET

### Endpoint
/categories

### Parameters
#### Query Parameters
- **budgetId** (string) - Optional - The ID of the budget to filter categories by.
- **sortBy** (string) - Optional - Sort field with +/- prefix for ASC/DESC. Allowed: createdAt, updatedAt. Example: -createdAt

### Response
#### Success Response (200)
- **agentHints** (AgentHintsArray) - Hints related to agents.
- **categories** (array) - An array of Category objects.
- **X-Last-Data-Change-At** (string) - Timestamp of the last data change.
- **X-Last-Data-Change-Rev** (string) - Revision of the last data change.
- **X-RateLimit-Limit** (integer) - The maximum number of requests allowed in the current time window.
- **X-RateLimit-Remaining** (integer) - The number of requests remaining in the current time window.
- **X-Sync-In-Progress** (boolean) - Indicates if a synchronization process is currently in progress.

#### Error Response
- **400**: Bad Request - Invalid parameter value.
- **401**: Unauthorized - Authentication failed.
- **429**: Rate limit exceeded. Check `Retry-After` header for when to retry.
```

--------------------------------

### Get Accounts

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a list of all financial accounts associated with the user. This endpoint provides a comprehensive overview of all accounts, including their details and balances.

```APIDOC
## GET /api/v1/accounts

### Description
Retrieves a list of all financial accounts associated with the user. This endpoint provides a comprehensive overview of all accounts, including their details and balances.

### Method
GET

### Endpoint
/api/v1/accounts

### Parameters
#### Query Parameters
- **archived** (boolean) - Optional - If true, only archived accounts are returned. Defaults to false.
- **includeArchived** (boolean) - Optional - Alias for `archived`. If true, only archived accounts are returned. Defaults to false.

### Response
#### Success Response (200)
- **accounts** (array) - A list of account objects.
  - **id** (string) - Unique identifier for the account.
  - **name** (string) - The name of the account.
  - **accountType** (string) - The type of the account.
  - **initialBalance** (object) - The initial balance of the account.
    - **currencyCode** (string) - The ISO 4217 currency code.
    - **value** (number) - The amount of the balance.
  - **color** (string) - The hex color code for the account.
  - **excludeFromStats** (boolean) - Whether the account is excluded from statistics.
  - **archived** (boolean) - Whether the account is archived.
  - **createdAt** (string) - Timestamp of when the account was created (ISO 8601 UTC).
  - **updatedAt** (string) - Timestamp of when the account was last updated (ISO 8601 UTC).

### Response Example
{
  "accounts": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "My Checking Account",
      "accountType": "CurrentAccount",
      "initialBalance": {
        "currencyCode": "USD",
        "value": 1000.50
      },
      "color": "#1e90ff",
      "excludeFromStats": false,
      "archived": false,
      "createdAt": "2024-03-15T10:00:00.000Z",
      "updatedAt": "2024-03-15T10:00:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
      "name": "Savings Account",
      "accountType": "SavingAccount",
      "initialBalance": {
        "currencyCode": "EUR",
        "value": 5000.00
      },
      "color": "#32cd32",
      "excludeFromStats": false,
      "archived": false,
      "createdAt": "2024-03-10T09:00:00.000Z",
      "updatedAt": "2024-03-10T09:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Get Budgets

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a paginated list of budgets. Supports filtering by ID, name, currency, closed status, type, labels, and accounts. The default order is by creation date, newest first.

```APIDOC
## GET /v1/api/budgets

### Description
Returns paginated list of budgets. Default order: newest first (-createdAt).

### Method
GET

### Endpoint
/v1/api/budgets

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30).
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions. (default: false).
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **name** (string) - Optional - Filter by name. Requires text prefix.
- **currencyCode** (string) - Optional - Filter by currency code (ISO 4217). Exact match, case-insensitive.
- **closed** (boolean) - Optional - Filter by closed flag. true = only closed budgets, false = only open budgets. Omit to return both.
- **type** (string) - Optional - Filter by budget type (exact match). BUDGET_ALL is a read-only legacy type that cannot be created.
  *Allowed values:*
  - `BUDGET_INTERVAL_WEEK`
  - `BUDGET_INTERVAL_MONTH`
  - `BUDGET_INTERVAL_YEAR`
  - `BUDGET_ALL`
  - `BUDGET_CUSTOM`
- **labelId** (string) - Optional - Filter by label ID. Returns entities that include this label.
- **accountId** (string) - Optional - Filter by account ID. Returns budgets that include this account.
- **categoryId** (string) - Optional - Filter by category ID. Comma-separated for multiple values. Special value 'unknown' expands to IDs of 3 categories: Unknown income, Unknown expense, and Uncategorized. Max 10 values.

### Responses
#### Success Response (200)
- (Response schema not fully provided in source text, but would typically include a list of budget objects)

#### Error Responses
- (Error responses not fully detailed in source text, but may include 400, 401, 429, 500 as seen in other endpoints.)
```

--------------------------------

### Get Record Rules

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a paginated list of automatic categorization rules for financial records. Rules are ordered by creation date, newest first by default. This endpoint is part of the Classification tag.

```APIDOC
## GET /v1/api/record-rules

### Description
Returns paginated list of automatic categorization rules for records. Default order: newest first (-createdAt).

### Method
GET

### Endpoint
/v1/api/record-rules

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions.
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **name** (string) - Optional - Filter by name. Requires text prefix.
- **labelId** (string) - Optional - Filter by label ID. Returns entities that include this label.
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix.
- **updatedAt** (string) - Optional - Filter by last sync timestamp (when entity was last updated in the API database). Requires range prefix.

### Response
#### Success Response (200)
- **agentHints** (AgentHintsArray) - Description
- **recordRules** (array) - Description

#### Response Example
{
  "example": "response body"
}

### Security
- BearerAuth
```

--------------------------------

### Get Standing Orders

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a paginated list of standing orders. This endpoint supports filtering by various criteria such as ID, name, currency, labels, and timestamps. It also allows for AI agent hints and includes total count if requested.

```APIDOC
## GET /v1/api/standing-orders

### Description
Returns paginated list of standing orders. Default order: newest first (-createdAt).

### Method
GET

### Endpoint
/v1/api/standing-orders

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30).
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions. (default: false).
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **name** (string) - Optional - Filter by name. Requires text prefix.
- **currencyCode** (string) - Optional - Filter by currency code (ISO 4217). Exact match, case-insensitive.
- **labelId** (string) - Optional - Filter by label ID. Returns entities that include this label.
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix.
- **updatedAt** (string) - Optional - Filter by last sync timestamp (when entity was last updated in the API database). Requires range prefix.

### Responses
#### Success Response (200)
- **standingOrders** (array) - List of standing orders.
- **agentHints** (array) - Structured hints for AI agents.

#### Error Responses
- **400** - Bad Request - Invalid parameter value.
- **401** - Unauthorized
- **429** - Rate limit exceeded.
- **500** - Internal server error.
```

--------------------------------

### Get Records

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a list of financial records. Supports extensive filtering by various criteria such as ID, account, date, category, labels, notes, amounts, and more. Pagination and sorting options are available.

```APIDOC
## GET /records

### Description
Retrieves a list of financial records. Supports extensive filtering by various criteria such as ID, account, date, category, labels, notes, amounts, and more. Pagination and sorting options are available.

### Method
GET

### Endpoint
/records

### Parameters
#### Query Parameters
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **accountId** (string) - Optional - Filter by account ID (exact match). When omitted, returns records from all accounts. Use /accounts to find valid account IDs.
- **recordDate** (string) - Optional - Filter by transaction date. Requires range prefix (e.g. `gte.2024-01-01`, `lt.2024-04-01`). If omitted, a default 3-month window is applied automatically. Provide any single bound to override the default. The actual applied filter is returned in `appliedRecordDateFilters`.
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions.
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **categoryId** (string) - Optional - Filter by category ID. Comma-separated for multiple values. Special value 'unknown' expands to IDs of 3 categories: Unknown income, Unknown expense, and Uncategorized. Max 10 values.
- **labelId** (string) - Optional - Filter by label ID - returns records that have this label
- **note** (string) - Optional - Filter by note. Requires text prefix.
- **counterParty** (string) - Optional - Filter records by counter party (payee/payer). Requires text prefix.
- **amount** (string) - Optional - Filter by transaction amount. Requires range prefix. Applied to amount.value (decimal format, e.g., 100.50).
- **baseAmount** (string) - Optional - Filter by base currency amount (amount converted to user's profile currency). Requires range prefix. Applied to baseAmount.value.
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix.
- **updatedAt** (string) - Optional - Filter by last sync timestamp (when entity was last updated in the API database). Requires range prefix.
- **recordType** (string) - Optional - Filter by record type. Enum: [expense, income]
- **paymentType** (string) - Optional - Filter by payment type. Enum: [cash, debit_card, credit_card, transfer, voucher, mobile_payment, web_payment]
- **recordState** (string) - Optional - Filter by record state. Comma-separated for multiple values (e.g. recordState=reconciled,uncleared). Valid values: reconciled, cleared, uncleared.
- **source** (string) - Optional - Filter by record creation source. Comma-separated for multiple values (e.g. source=mcp,rest). Valid values: android, ios, web, rest, mcp, backend, missing.
- **sort** (string) - Optional - Sort results by field. Prefix with + for ascending, - for descending. Supported fields: recordDate, amount, createdAt, updatedAt. Default: -recordDate (newest first).

### Request Example
```json
{
  "example": "GET /records?id=3f8e2a6b-9c4d-4e1f-b2a7-5d8c3e9f1a4b&recordDate=gte.2024-01-01&limit=50"
}
```

### Response
#### Success Response (200)
- **appliedRecordDateFilters** (string) - The actual record date filters applied to the query.
- **total** (integer) - The total number of items matching the query (only if `withTotal` is true).
- **records** (array) - An array of record objects.

#### Response Example
```json
{
  "example": {
    "appliedRecordDateFilters": "gte.2024-01-01",
    "total": 100,
    "records": [
      {
        "id": "3f8e2a6b-9c4d-4e1f-b2a7-5d8c3e9f1a4b",
        "accountId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "recordDate": "2024-01-15",
        "amount": {"value": "50.00", "currency": "USD"},
        "description": "Groceries",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}
```
```

--------------------------------

### Get Accounts

Source: https://rest.budgetbakers.com/wallet/openapi

Retrieves a paginated list of financial accounts. Supports filtering by various criteria such as ID, name, type, currency, and timestamps, as well as sorting and including AI agent hints or total counts.

```APIDOC
## GET /accounts

### Description
Returns paginated list of financial accounts. Supports filtering by ID, name, type, currency, creation and update timestamps, archived status, and budget ID. Can also include AI agent hints and total count.

### Method
GET

### Endpoint
/accounts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (1-200, default: 30)
- **offset** (integer) - Optional - Number of items to skip (default: 0). Used for pagination.
- **agentHints** (boolean) - Optional - Enable AI agent hints in response. When true, includes structured hints to help AI agents understand the response and take follow-up actions. (default: false)
- **withTotal** (boolean) - Optional - When true, the response includes a total count of all matching items (requires an additional database query). Default: false.
- **id** (string) - Optional - Filter by ID. Supports comma-separated list for multiple IDs (max 30).
- **name** (string) - Optional - Filter by name. Requires text prefix.
- **accountType** (string) - Optional - Filter accounts by account type. Case-insensitive. Allowed values: General, Cash, CurrentAccount, CreditCard, SavingAccount, Bonus, Insurance, Investment, Loan, Mortgage, Overdraft.
- **currencyCode** (string) - Optional - Filter by currency code (ISO 4217). Exact match, case-insensitive.
- **createdAt** (string) - Optional - Filter by creation timestamp. Requires range prefix.
- **updatedAt** (string) - Optional - Filter by last sync timestamp. Requires range prefix.
- **archived** (boolean) - Optional - Filter by archived status. true=archived only, false=active only, omit for all.
- **budgetId** (string) - Optional - Filter items tracked by a specific budget.
- **sortBy** (string) - Optional - Sort field with +/- prefix for ASC/DESC. Allowed: createdAt, updatedAt. Example: -createdAt

### Response
#### Success Response (200)
- **accounts** (array) - List of accounts.
- **agentHints** (array) - Structured hints for AI agents.

#### Error Response
- **400** - Bad Request - Invalid parameter value
- **401** - Unauthorized
- **429** - Rate limit exceeded. Check `Retry-After` header for when to retry.
- **500** - Internal server error. The request was valid but processing failed due to a temporary issue. Retry the request later.
```

--------------------------------

### Create Account

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Creates a new financial account within the Wallet application.

```APIDOC
## POST /v1/api/accounts

### Description
Creates a new financial account within the Wallet application.

### Method
POST

### Endpoint
/v1/api/accounts

### Parameters
#### Request Body
- **account** (object) - Required - The details of the account to create.
  - **name** (string) - Required - The name of the account.
  - **currency** (string) - Required - The currency of the account (e.g., USD, EUR).
  - **initial_balance** (number) - Optional - The starting balance for the account.

### Request Example
{
  "account": {
    "name": "Savings Account",
    "currency": "EUR",
    "initial_balance": 500.00
  }
}

### Response
#### Success Response (200)
- **account** (object) - The newly created account object, including its ID.

### Response Example
{
  "account": {
    "id": "acc_456",
    "name": "Savings Account",
    "currency": "EUR",
    "balance": 500.00
  }
}
```

--------------------------------

### Create Account

Source: https://rest.budgetbakers.com/wallet/openapi

Creates a new financial account. You can specify the account type, currency, initial balance, and other details.

```APIDOC
## POST /accounts

### Description
Creates a new financial account.

### Method
POST

### Endpoint
/accounts

### Request Body
- **name** (string) - Required - Maximum 80 characters.
- **accountType** (string) - Required - Must be one of: General, Cash, CurrentAccount, SavingAccount, Insurance.
- **currencyCode** (string) - Required - 3-letter fiat currency code.
- **initialBalance** (number) - Required - Initial balance amount (e.g. 1500.50).
- **bankAccountNumber** (string) - Optional - Bank account number or IBAN (max 80 chars).
- **color** (string) - Optional - Universal color name. Randomly assigned if omitted. Must be one of: Blue, Charcoal, CoffeeBrown, DarkPurple, Green, LightBlue, Lime, Orange, PineGreen, Pink, Purple, Red, Stone, Turquoise, Wine, Yellow.
- **excludeFromStats** (boolean) - Optional - Defaults to false.

### Request Example
{
  "name": "My new account",
  "accountType": "General",
  "currencyCode": "EUR",
  "initialBalance": 0
}

### Response
#### Success Response (200)
- **account** (object) - Details of the created account.
- **agentHints** (array) - Hints provided by the agent.
```

--------------------------------

### Creating Budgets

Source: https://rest.budgetbakers.com/wallet/reference

Creates a new budget. A maximum of 50 budgets are allowed per user.

```APIDOC
## POST /budgets

### Description
Creates a new budget. A maximum of 50 budgets are allowed per user.

### Method
POST

### Endpoint
/budgets

### Parameters
#### Request Body
- **name** (string) - Yes - Max 80 characters
- **currencyCode** (string) - Yes - ISO 4217 fiat currency code. Immutable after creation.
- **type** (string) - Yes - `BUDGET_INTERVAL_WEEK`, `BUDGET_INTERVAL_MONTH`, `BUDGET_INTERVAL_YEAR`, or `BUDGET_CUSTOM`. Immutable after creation.
- **limit** (DECIMAL(19,2)) - Yes - Budget spending limit. Must be > 0.
- **startDate** (string) - No - YYYY-MM-DD format. Required for `BUDGET_CUSTOM` type. Must be ≥ `endDate`.
- **endDate** (string) - No - YYYY-MM-DD format. Required for `BUDGET_CUSTOM` type. Must be ≥ `startDate`.
- **categoryIds** (array) - No - Array of category UUIDs to track. If left empty, all are tracked.
- **accountIds** (array) - No - Array of account UUIDs. Limits budget tracking to these accounts. If left empty, all are tracked.
- **labelIds** (array) - No - Array of label UUIDs. If left empty, all are tracked.
```

--------------------------------

### POST /accounts

Source: https://rest.budgetbakers.com/wallet/reference

Creates a single new account. Supports a maximum of 50 accounts per user. Account details include name, type, currency, and initial balance.

```APIDOC
## POST /accounts

### Description
Creates a single new account. Supports a maximum of 50 accounts per user. Account details include name, type, currency, and initial balance.

### Method
POST

### Endpoint
/accounts

### Parameters
#### Request Body
- **name** (string) - Required - Max 80 characters
- **accountType** (string) - Required - One of: `General`, `Cash`, `CurrentAccount`, `SavingAccount`, `Insurance`. Other types are read-only.
- **currencyCode** (string) - Required - ISO 4217 fiat currency code. Immutable after creation.
- **initialBalance** (number) - Required - DECIMAL(19,2) precision
- **color** (string) - Optional - One of 16 supported colors. Randomly assigned if omitted.

### Request Example
```json
{
  "name": "My Checking Account",
  "accountType": "CurrentAccount",
  "currencyCode": "USD",
  "initialBalance": 1000.50,
  "color": "#FF0000"
}
```

### Response
#### Success Response (201 Created)
- **accountId** (string) - The UUID of the newly created account.
- **name** (string) - The name of the account.
- **accountType** (string) - The type of the account.
- **currencyCode** (string) - The currency code of the account.
- **initialBalance** (number) - The initial balance of the account.
- **color** (string) - The color of the account.

#### Response Example (201 Created)
```json
{
  "accountId": "uuid-of-new-account",
  "name": "My Checking Account",
  "accountType": "CurrentAccount",
  "currencyCode": "USD",
  "initialBalance": 1000.50,
  "color": "#FF0000"
}
```
```

--------------------------------

### Create Budget

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Creates a new budget for a specific period and category.

```APIDOC
## POST /v1/api/budgets

### Description
Creates a new budget for a specific period and category.

### Method
POST

### Endpoint
/v1/api/budgets

### Parameters
#### Request Body
- **budget** (object) - Required - The details of the budget to create.
  - **name** (string) - Required - The name of the budget.
  - **amount** (number) - Required - The budgeted amount.
  - **currency** (string) - Required - The currency of the budget.
  - **period** (string) - Required - The budget period (e.g., 'monthly', 'yearly').
  - **category_id** (string) - Optional - The ID of the category this budget applies to.

### Request Example
{
  "budget": {
    "name": "Monthly Entertainment Budget",
    "amount": 200.00,
    "currency": "USD",
    "period": "monthly",
    "category_id": "cat_ent"
  }
}

### Response
#### Success Response (200)
- **budget** (object) - The newly created budget object.

### Response Example
{
  "budget": {
    "id": "bud_def",
    "name": "Monthly Entertainment Budget",
    "amount": 200.00,
    "currency": "USD",
    "period": "monthly",
    "category_id": "cat_ent"
  }
}
```

--------------------------------

### Get Standing Order Items

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves a list of individual occurrences or items for standing orders.

```APIDOC
## GET /v1/api/standing-orders/items

### Description
Retrieves a list of individual occurrences or items for standing orders.

### Method
GET

### Endpoint
/v1/api/standing-orders/items

### Response
#### Success Response (200)
- **standing_order_items** (array) - A list of standing order item objects.

### Response Example
{
  "standing_order_items": [
    {
      "id": "soi_123",
      "standing_order_id": "so_abc",
      "date": "2023-11-01",
      "amount": 1200.00,
      "status": "processed"
    }
  ]
}
```

--------------------------------

### Get API Usage Statistics

Source: https://rest.budgetbakers.com/wallet/openapi/ui

Retrieves statistics about API usage, such as request counts and limits.

```APIDOC
## GET /v1/api/api-usage/stats

### Description
Retrieves statistics about API usage, such as request counts and limits.

### Method
GET

### Endpoint
/v1/api/api-usage/stats

### Response
#### Success Response (200)
- **api_usage_stats** (object) - An object containing API usage statistics.

### Response Example
{
  "api_usage_stats": {
    "requests_today": 1500,
    "limit_today": 10000,
    "requests_this_month": 30000,
    "limit_this_month": 300000
  }
}
```

--------------------------------

### POST /accounts

Source: https://rest.budgetbakers.com/wallet/openapi

Create a new financial account. This endpoint allows for the creation of a new account with specified details. It returns the created account information upon success.

```APIDOC
## POST /accounts

### Description
Create a new financial account.

### Method
POST

### Endpoint
/accounts

### Request Body
- **(object)** - Required - Schema reference: `#/components/schemas/CreateAccountRequest`

### Responses
#### Success Response (201)
- **(object)** - Account created. Schema reference: `#/components/schemas/CreateAccountResponse`

#### Error Response (400)
- **(object)** - Bad Request - Invalid parameter value. Schema reference: `#/components/schemas/ValidationError`

#### Error Response (401)
- **(object)** - Unauthorized. Schema reference: `#/components/schemas/Error`

#### Error Response (429)
- **(object)** - Rate limit exceeded. Check `Retry-After` header for when to retry. Schema reference: `#/components/schemas/RateLimitError`
  - **Retry-After** (integer) - Seconds to wait before retrying.

#### Error Response (500)
- **(object)** - Internal server error. The request was valid but processing failed due to a temporary issue. Retry the request later. Schema reference: `#/components/schemas/Error`
```

--------------------------------

### Create Account

Source: https://rest.budgetbakers.com/wallet/openapi

Creates a new financial account for the user. This endpoint allows for the creation of various account types, including general, cash, current, savings, and insurance accounts.

```APIDOC
## POST /api/v1/accounts

### Description
Creates a new financial account for the user. This endpoint allows for the creation of various account types, including general, cash, current, savings, and insurance accounts.

### Method
POST

### Endpoint
/api/v1/accounts

### Parameters
#### Request Body
- **name** (string) - Required - The name of the account.
- **accountType** (string) - Required - The type of the account (e.g., 'General', 'Cash', 'CurrentAccount', 'SavingAccount', 'Insurance').
- **initialBalance** (object) - Optional - The initial balance of the account.
  - **currencyCode** (string) - Required - The ISO 4217 currency code.
  - **value** (number) - Required - The amount of the balance.
- **color** (string) - Optional - A hex color code for the account.
- **excludeFromStats** (boolean) - Optional - Whether to exclude this account from statistics.

### Request Example
{
  "name": "My New Checking Account",
  "accountType": "CurrentAccount",
  "initialBalance": {
    "currencyCode": "USD",
    "value": 1000.50
  },
  "color": "#1e90ff",
  "excludeFromStats": false
}

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the newly created account.
- **name** (string) - The name of the account.
- **accountType** (string) - The type of the account.
- **initialBalance** (object) - The initial balance of the account.
  - **currencyCode** (string) - The ISO 4217 currency code.
  - **value** (number) - The amount of the balance.
- **color** (string) - The hex color code for the account.
- **excludeFromStats** (boolean) - Whether the account is excluded from statistics.
- **createdAt** (string) - Timestamp of when the account was created (ISO 8601 UTC).
- **updatedAt** (string) - Timestamp of when the account was last updated (ISO 8601 UTC).

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "My New Checking Account",
  "accountType": "CurrentAccount",
  "initialBalance": {
    "currencyCode": "USD",
    "value": 1000.50
  },
  "color": "#1e90ff",
  "excludeFromStats": false,
  "createdAt": "2024-03-15T10:00:00.000Z",
  "updatedAt": "2024-03-15T10:00:00.000Z"
}
```
Tokens:
Raw