Feature Request: Upload statements to the Statement Vault via the REST API

[Taaqif]

Summary

Add an endpoint to the REST API (/api/v1) for uploading statement documents into the Statement Vault, e.g. POST /api/v1/account_statements, authenticated with an API key (X-Api-Key) like the other endpoints.

Why

The Statement Vault is a great place to keep primary-source documents, and coverage/reconciliation make it more useful the more complete it is. Today a statement can only get there through the web UI or the MCP upload_account_statement tool.

Tools that already talk to the API, such as bank sync scripts that import transactions with POST /api/v1/imports, could also download each month's statement PDF from the bank and file it automatically. Doing that over MCP means a separate token (MCP_API_TOKEN + MCP_USER_EMAIL, or OAuth) and a JSON-RPC client just for this one call, while everything else uses the regular API key.

Proposal

POST /api/v1/account_statements (multipart):

• file (required): PDF, CSV or XLSX, same limits as the vault upload (25 MB)
• account_id (optional): link to this account on upload; without it the vault suggests a match as it does today
• optional hints already supported by the UI: period_start_on, period_end_on, opening_balance, closing_balance, currency

Response: the statement (id, account_id, detected period, institution, suggested account + confidence) and duplicate: true when the same file (SHA-256) is already stored, mirroring the MCP tool.

Nice to have:

• GET /api/v1/account_statements?account_id= (list, with period) so a client can tell which months it has already filed
• GET /api/v1/accounts/:id/statement_coverage?year= (same data as the MCP get_statement_coverage tool)
• an API key scope for it (write), so a key can be limited to imports + statements

Notes

The behaviour already exists (AccountStatement.prepare_upload! / create_from_prepared_upload! and the MCP tool), so this would mostly be a thin controller + jbuilder views + docs in the API spec.

[Taaqif]

Implemented in PR #4826