# How Securo Handles Budget Tracking Through Its API: A Complete CRUD Guide

> Learn how Securo handles budget tracking via its API with this CRUD guide. Explore budget management, month-over-month comparisons, and cache invalidation for synchronized data.

- Repository: [securo-finance/securo](https://github.com/securo-finance/securo)
- Tags: api-reference
- Published: 2026-08-28

---

**Securo exposes budget tracking through a REST-style `/budgets` API that supports listing, creating, updating, deleting budgets, and retrieving month-over-month comparisons, with automatic cache invalidation to keep data synchronized.**

The Securo open-source finance platform provides a structured API layer for personal and business budgeting. All budget operations are accessible via the `budgets` namespace in [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts), enabling both the React frontend and external integrations to manage financial targets programmatically.

## Securo Budget API Endpoints Overview

The budget tracking system follows a standard **CRUD pattern** with an additional analytics endpoint. Each operation maps to a specific HTTP method and route under the `/budgets` base path.

| Operation | HTTP Method | Endpoint | Purpose |
|-----------|-------------|----------|---------|
| **List budgets** | `GET` | `/budgets` | Retrieve all budgets for a specified month |
| **Create budget** | `POST` | `/budgets` | Add a new budget entry with category and amount |
| **Update budget** | `PATCH` | `/budgets/:id` | Modify an existing budget's fields |
| **Delete budget** | `DELETE` | `/budgets/:id` | Remove a budget by its unique identifier |
| **Budget comparison** | `GET` | `/budgets/comparison` | Get spending vs. budgeted analytics |

## List Budgets with Optional Month Filtering

The **GET `/budgets`** endpoint returns budget records scoped to a time period. When called without parameters, it defaults to the current month.

```typescript
import { budgets } from '@/lib/api'

async function fetchBudgets(month: string) {
  const data = await budgets.get({ month })
  console.log('Budgets for', month, data)
}

```

The `month` query parameter accepts ISO-8601 month strings (e.g., `"2024-09"`), as defined in [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts) at lines 1008–1025.

## Create a New Budget Entry

New budgets require a `category_id`, `amount`, and `month`. The optional `is_recurring` flag enables automatic rollover for recurring expenses.

```typescript
import { budgets } from '@/lib/api'

async function addBudget() {
  const newBudget = {
    category_id: 'c123',
    amount: 500,
    month: '2024-09',
    is_recurring: true,
  }
  const created = await budgets.create(newBudget)
  console.log('Created budget:', created)
}

```

The server validates these fields against the `Budget` type definition in [`frontend/src/types/index.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/types/index.ts) (line 722), which includes `budget_amount`, `category_id`, and related properties.

## Update Existing Budget Amounts

Budget modifications use **PATCH** semantics, allowing partial updates. Pass only the fields you want to change.

```typescript
import { budgets } from '@/lib/api'

async function modifyBudget(id: string, newAmount: number) {
  const updated = await budgets.update(id, { amount: newAmount })
  console.log('Updated budget:', updated)
}

```

## Delete Budgets by ID

Remove budget entries with a simple delete call:

```typescript
import { budgets } from '@/lib/api'

async function removeBudget(id: string) {
  await budgets.delete(id)
  console.log('Budget deleted')
}

```

## Retrieve Budget Comparison Analytics

The **comparison endpoint** aggregates spending data against budgeted amounts, powering the month-over-month visualizations in Securo's UI.

```typescript
import { budgets } from '@/lib/api'

async function getComparison(month: string) {
  const comparison = await budgets.comparison({ month })
  console.log('Comparison data:', comparison)
}

```

This endpoint accepts the same `month` query parameter as the list operation.

## Automatic Cache Invalidation for Data Consistency

Securo's client library ensures UI consistency through proactive cache management. Located in [`frontend/src/lib/invalidate-queries.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/invalidate-queries.ts) (line 23), the invalidation logic triggers after every mutation:

```typescript
queryClient.invalidateQueries({ queryKey: ['budgets'] })

```

This mechanism guarantees that **create, update, and delete operations** immediately propagate to all active views, eliminating stale data without manual refresh.

## Key Source Files in Securo's Budget API

| File | Location | Responsibility |
|------|----------|--------------|
| [`api.ts`](https://github.com/securo-finance/securo/blob/main/api.ts) | [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts) lines 1008–1025 | Budget route definitions and request implementations |
| [`invalidate-queries.ts`](https://github.com/securo-finance/securo/blob/main/invalidate-queries.ts) | [`frontend/src/lib/invalidate-queries.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/invalidate-queries.ts) line 23 | Post-mutation cache invalidation |
| [`types/index.ts`](https://github.com/securo-finance/securo/blob/main/types/index.ts) | [`frontend/src/types/index.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/types/index.ts) line 722 | TypeScript interfaces for `Budget` objects |

## Summary

- Securo implements **five budget API operations** under the `/budgets` namespace: list, create, update, delete, and comparison.
- All endpoints are accessible through the centralized `budgets` client in [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts).
- The API supports **month-based filtering** via query parameters for temporal budget analysis.
- **Automatic cache invalidation** keeps UI state synchronized without manual intervention.
- Type definitions in [`frontend/src/types/index.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/types/index.ts) ensure type-safe interactions across the codebase.

## Frequently Asked Questions

### What authentication does Securo's budget API require?

Based on the source code implementation in `securo-finance/securo`, the budget API routes integrate with Securo's standard permission-checking middleware. The actual authentication layer validates sessions or API tokens before reaching the budget handlers, though the specific mechanism depends on your deployed configuration.

### Can external applications use Securo's budget API?

Yes. The `budgets` namespace in [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts) is designed as a generic HTTP client that any TypeScript or JavaScript application can import. The REST endpoints accept standard JSON payloads and return typed responses, making integration straightforward for third-party tools.

### How does Securo handle recurring budgets?

The `is_recurring` boolean field in the **create budget** endpoint flags entries for rollover behavior. According to the type definitions in [`frontend/src/types/index.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/types/index.ts), this property is optional—when omitted, budgets default to non-recurring single-month entries.

### What data format does the budget comparison endpoint return?

The comparison endpoint returns aggregated analytics showing actual spending versus budgeted amounts per category. The exact structure aligns with Securo's internal reporting schema, designed to populate UI visualizations with month-over-month variance data.