Routes

interfaces.report.routes

Summary

Report REST handlers — thin API entry points for the reports resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to ReportService via request.app.state.db_resources and translate domain validation errors into 400 responses.

Classes

Functions

create_report async

create_report(request: Request, body: dict)

Generate a report snapshot from a query definition.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Report query payload; validated into a ReportQuery.	required

Returns:

Name	Type	Description
ReportSnapshotDocument		The generated snapshot.

Raises:

Type	Description
HTTPException	400 when the query payload is invalid.

delete_report async

delete_report(request: Request, id: str)

Delete a report snapshot by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Report snapshot id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when the snapshot does not exist.

get_report async

get_report(
    request: Request,
    id: str,
    granularity: Optional[List[str]] = Query(None),
    period_ids: Optional[List[str]] = Query(None),
    flow: str = "outflows",
    payee: Optional[List[str]] = Query(None),
    tags: Optional[List[str]] = Query(None),
)

Fetch a report snapshot with optional granularity, flow, and filter overrides.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Report snapshot id.	required
granularity	Optional[List[str]]	Granularities to materialize; empty means the snapshot's default set.	Query(None)
period_ids	Optional[List[str]]	Period labels to constrain output.	Query(None)
flow	str	Flow filter of inflows, outflows, or both. Defaults to outflows.	'outflows'
payee	Optional[List[str]]	Payee names to include.	Query(None)
tags	Optional[List[str]]	Tag paths to include.	Query(None)

Returns:

Name	Type	Description
Report		The fetched report.

Raises:

Type	Description
HTTPException	400 when the report arguments are invalid.
HTTPException	404 when the snapshot does not exist.

list_reports async

list_reports(
    request: Request, offset: int = 0, limit: int = 100
)

List report snapshots with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
offset	int	Number of snapshots to skip (offset). Defaults to 0.	0
limit	int	Maximum number of snapshots to return. Defaults to 100.	100

Returns:

Type	Description
	list[ReportSnapshotDocument]: Matching snapshots from the report service.