Securo API Endpoints for Reporting: A Complete Guide to Financial Data Access

The Securo API provides three core reporting endpoints—GET /api/reports/net-worth, GET /api/reports/income-expenses, and GET /api/reports/cash-flow—that deliver time-series financial insights with configurable parameters for time windows, granularity, and filtering.

Securo, an open-source financial platform by securo-finance, exposes these reporting capabilities through its FastAPI-based backend. This guide covers each Securo API endpoint for reporting, including their parameters, source code locations, and practical implementation examples.

Net-Worth Report Endpoint

The net-worth endpoint returns a time-series of the workspace's total net worth as defined in backend/app/api/reports.py lines 15–28.

Key Parameters

Parameter	Type	Description
months	integer	Limits the time window (default varies by implementation)
interval	string	Aggregation granularity: daily, weekly, monthly
period=ytd	string	Request a year-to-date view
account/asset filters	various	Filter by specific accounts or asset groups

Example Request

import requests

BASE_URL = "https://your-securo-instance.com/api"
TOKEN = "YOUR_AUTH_TOKEN"

headers = {"Authorization": f"Bearer {TOKEN}"}

# Net-Worth report (last 12 months, monthly granularity)

resp = requests.get(
    f"{BASE_URL}/reports/net-worth",
    params={"months": 12, "interval": "monthly"},
    headers=headers,
)
print("Net-Worth:", resp.json())

Income-Expenses Report Endpoint

The income-expenses endpoint provides a breakdown of income versus expenses over time, implemented in backend/app/api/reports.py lines 31–45.

Key Parameters

Parameter	Type	Description
months	integer	Number of months to include
days	integer	Exact rolling window in days (alternative to months)
interval	string	Aggregation granularity
period=ytd	string	Year-to-date view
account filters	various	Filter by specific accounts

Example Request

# Income-Expenses report (YTD, weekly granularity)

resp = requests.get(
    f"{BASE_URL}/reports/income-expenses",
    params={"period": "ytd", "interval": "weekly"},
    headers=headers,
)
print("Income-Expenses:", resp.json())

Cash-Flow Report Endpoint

The cash-flow endpoint shows cash inflow and outflow patterns, defined in backend/app/api/reports.py lines 48–60.

Key Parameters

Parameter	Type	Default	Description
months	integer	6	Time window for the report
interval	string	daily	Aggregation granularity
baseline	boolean/string	—	Include starting balance when "true"
account filters	various	—	Filter by specific accounts

Example Request

# Cash-Flow report (6-month daily view, with baseline)

resp = requests.get(
    f"{BASE_URL}/reports/cash-flow",
    params={"months": 6, "interval": "daily", "baseline": "true"},
    headers=headers,
)
print("Cash-Flow:", resp.json())

Authentication and Router Architecture

All Securo API endpoints for reporting require Bearer token authentication. The reports router is mounted under the /api/reports prefix in the main FastAPI application at backend/app/main.py line 79.

Router Registration

# From backend/app/main.py (line 79)

app.include_router(reports.router, prefix="/api/reports", tags=["reports"])

This architecture means all three endpoints share:

• Unified authentication middleware
• Common response schema (ReportResponse from backend/app/schemas/report.py)
• Consistent parameter validation patterns

Supporting Source Files

File	Purpose
backend/app/api/reports.py	Router definition with three GET endpoints
backend/app/main.py	FastAPI app with router mounting at line 79
backend/app/services/report_service.py	Business logic implementation for report generation
backend/app/schemas/report.py	ReportResponse schema shared across endpoints

Summary

• Three core endpoints serve net-worth, income-expenses, and cash-flow reporting needs
• Flexible parameters control time windows (months, days), granularity (interval), and view types (period=ytd, baseline)
• Common infrastructure in backend/app/api/reports.py ensures consistent authentication and response formatting
• Bearer token required for all requests as implemented in the securo-finance/securo repository

Frequently Asked Questions

What authentication is required for Securo reporting endpoints?

All three Securo API endpoints for reporting require a valid Bearer token in the Authorization header. The same authentication middleware protects these routes as the rest of the API, ensuring workspace-scoped access control.

Can I filter reports by specific accounts?

Yes. All three endpoints—net-worth, income-expenses, and cash-flow—support account filtering parameters. The exact parameter names are defined in backend/app/api/reports.py and processed through backend/app/services/report_service.py.

What intervals are supported for data aggregation?

According to the parameter definitions in the source code, you can specify daily, weekly, or monthly intervals via the interval parameter. The cash-flow endpoint defaults to daily, while other endpoints' defaults depend on the specific implementation in the service layer.

How do I request a year-to-date report instead of a rolling window?

Add period=ytd to your request parameters. This works for both the net-worth and income-expenses endpoints, overriding any months or days parameters to calculate from the start of the current year.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}