{"openapi":"3.1.0","info":{"title":"GET /api/v1/reports","version":"1.0.0","description":"List reports"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/reports":{"get":{"tags":["reports"],"summary":"List reports","description":"Retrieve all reports for a business with pagination.","operationId":"list_reports_api_v1_reports_get","parameters":[{"name":"client_visible_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Client Visible Only"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"Cursor"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Pagination limit","title":"Limit"},"description":"Pagination limit"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Pagination direction: 'next' or 'prev'","default":"next","title":"Direction"},"description":"Pagination direction: 'next' or 'prev'"},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to include total count (expensive - avoid if possible)","default":false,"title":"Include Total Count"},"description":"Whether to include total count (expensive - avoid if possible)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.","title":"Sort By"},"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None."},{"name":"descending","in":"query","required":false,"schema":{"type":"boolean","description":"Sort direction: true for descending (newest/largest first), false for ascending","default":true,"title":"Descending"},"description":"Sort direction: true for descending (newest/largest first), false for ascending"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportsListResponse"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ReportResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for this generated report. Use this ID to retrieve the report details or delete it. Example: '019ab37c-rpt1-7000-8000-000000000001'."},"business_id":{"type":"string","title":"Business Id","description":"UUID of the business this report belongs to. Reports are scoped to a single business and cannot be accessed by other businesses."},"report_name":{"type":"string","title":"Report Name","description":"The report type that was generated. Matches the report_name from the original request. Example: 'profit_and_loss', 'master_transactions', 'ar_report'."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the report was generated (ISO 8601 format). Example: '2026-01-15T14:00:00Z'."},"downloaded_at":{"type":"string","format":"date-time","title":"Downloaded At","description":"Timestamp of the most recent download of this report. Updated each time the report is accessed. Useful for tracking report usage."},"s3_bucket":{"type":"string","title":"S3 Bucket","description":"Name of the S3 bucket where the report file is stored. Format: 'dayzero-{environment}-reports'. Example: 'dayzero-prod-reports'."},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key (path) for the report file within the bucket. Format: 'reports/{business_id}/{report_type}_{dates}.xlsx'. Example: 'reports/019ab37c-bus1/master_transactions_2026-01-01_2026-12-31.xlsx'."},"generation_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Generation Params","description":"Dictionary of all parameters used to generate this report. Includes resolved dates (even when using tax_year/tax_quarter), filters, and any additional parameters. Useful for understanding report scope and audit purposes. Example: {'start_date': '2026-01-01', 'end_date': '2026-12-31', 'ledger_id': null}."},"download_url":{"type":"string","title":"Download Url","description":"Same-origin proxy URL for downloading the report file. Streams through the backend to avoid CORS and presigned-URL expiration issues. Requires Authorization and x-business-id headers."},"generated_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Generated By Name","description":"Display name of the user who generated this report, e.g. 'Sarah Chen'. Extracted from generation_params."}},"type":"object","required":["id","business_id","report_name","created_at","downloaded_at","s3_bucket","s3_key","download_url"],"title":"ReportResponse","description":"Response schema for a generated report.\n\nContains the report metadata and a pre-signed URL to download the Excel file.\nReports are stored in S3 and the signed URL provides temporary access (24 hours).\n\nThe generation_params field stores all the parameters used to create this report,\nwhich is useful for understanding the report's scope and for regenerating it.","example":{"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2024-01-15T14:00:00Z","download_url":"/api/v1/reports/download?s3_key=reports/019ab37c-bus1/profit_and_loss_2024-01.xlsx&filename=profit_and_loss_2024-01.xlsx","downloaded_at":"2024-01-15T14:00:00Z","generation_params":{"end_date":"2024-01-31","start_date":"2024-01-01"},"id":"019ab37c-rpt1-7000-8000-000000000001","report_name":"profit_and_loss","s3_bucket":"dayzero-reports","s3_key":"reports/019ab37c-bus1/profit_and_loss_2024-01.pdf"}},"ReportsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportResponse"},"type":"array","title":"Items","description":"List of items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total number of items (null when not calculated for performance)"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Pagination limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for next page"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor","description":"Cursor for previous page"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous items"}},"type":"object","required":["items","has_next","has_prev"],"title":"ReportsListResponse","description":"Paginated list of generated reports."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}