Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/analytics/*.

Reports API

Generate, schedule, and export business reports.

Overview

The Reports API provides comprehensive reporting capabilities:

Feature	Description
Pre-built Reports	Standard industry reports
Custom Reports	Build your own reports
Scheduling	Automated report delivery
Export	PDF, Excel, CSV formats
Sharing	Email and link sharing

---

Available Report Types

Report	Description
sales_summary	Daily/weekly/monthly sales
product_mix	Item sales breakdown
labor_summary	Labor costs and hours
time_and_attendance	Employee time records
inventory_usage	Inventory consumption
waste_report	Waste tracking
financial_summary	P&L summary
tax_report	Tax collected by category
tips_report	Tips by employee
voids_comps	Voids and comps summary

---

Generate Report

Request

POST /api/v1/reports/generate
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "sales_summary",
  "location_ids": ["loc-xyz789"],
  "start_date": "2026-01-01",
  "end_date": "2026-01-18",
  "group_by": "day",
  "format": "pdf",
  "options": {
    "include_comparisons": true,
    "comparison_period": "previous_period"
  }
}

Parameters

Field	Type	Required	Description
type	string	Yes	Report type
location_ids	array	Yes	Locations to include
start_date	date	Yes	Report start date
end_date	date	Yes	Report end date
group_by	string	No	Grouping (day, week, month)
format	string	Yes	Output format (pdf, xlsx, csv)
options	object	No	Report-specific options

Response

{
  "id": "report-abc123",
  "status": "processing",
  "type": "sales_summary",
  "estimated_completion": "2026-01-18T12:01:00Z",
  "created_at": "2026-01-18T12:00:00Z"
}

---

Get Report Status

Request

GET /api/v1/reports/{report_id}
Authorization: Bearer {access_token}

Response

{
  "id": "report-abc123",
  "status": "completed",
  "type": "sales_summary",
  "download_url": "https://reports.olympuscloud.ai/download/abc123",
  "expires_at": "2026-01-25T12:00:00Z",
  "file_size_bytes": 245000,
  "format": "pdf",
  "created_at": "2026-01-18T12:00:00Z",
  "completed_at": "2026-01-18T12:00:45Z"
}

Report Status Values

Status	Description
pending	Report queued
processing	Report generating
completed	Report ready
failed	Report generation failed
expired	Download link expired

---

Download Report

Request

GET /api/v1/reports/{report_id}/download
Authorization: Bearer {access_token}

Returns the report file directly.

---

List Reports

Request

GET /api/v1/reports?
  location_id=loc-xyz789&
  type=sales_summary&
  limit=20
Authorization: Bearer {access_token}

Response

{
  "reports": [
    {
      "id": "report-abc123",
      "type": "sales_summary",
      "status": "completed",
      "period": {
        "start": "2026-01-01",
        "end": "2026-01-18"
      },
      "format": "pdf",
      "created_at": "2026-01-18T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

---

Schedule Report

Request

POST /api/v1/reports/schedules
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Weekly Sales Report",
  "type": "sales_summary",
  "location_ids": ["loc-xyz789"],
  "schedule": {
    "frequency": "weekly",
    "day_of_week": "monday",
    "time": "08:00",
    "timezone": "America/Los_Angeles"
  },
  "period": "previous_week",
  "format": "pdf",
  "recipients": [
    {"email": "manager@restaurant.com", "name": "John Manager"},
    {"email": "owner@restaurant.com", "name": "Jane Owner"}
  ],
  "options": {
    "include_comparisons": true
  }
}

Schedule Frequencies

Frequency	Parameters
daily	time
weekly	day_of_week, time
biweekly	day_of_week, time
monthly	day_of_month, time
quarterly	month_of_quarter, day_of_month, time

Response

{
  "id": "schedule-xyz789",
  "name": "Weekly Sales Report",
  "status": "active",
  "next_run": "2026-01-20T08:00:00-08:00",
  "created_at": "2026-01-18T12:00:00Z"
}

---

List Schedules

Request

GET /api/v1/reports/schedules?location_id=loc-xyz789
Authorization: Bearer {access_token}

Response

{
  "schedules": [
    {
      "id": "schedule-xyz789",
      "name": "Weekly Sales Report",
      "type": "sales_summary",
      "frequency": "weekly",
      "status": "active",
      "next_run": "2026-01-20T08:00:00-08:00",
      "last_run": "2026-01-13T08:00:00-08:00",
      "last_status": "completed"
    }
  ]
}

---

Update Schedule

Request

PATCH /api/v1/reports/schedules/{schedule_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "recipients": [
    {"email": "manager@restaurant.com", "name": "John Manager"}
  ],
  "schedule": {
    "time": "07:00"
  }
}

---

Pause/Resume Schedule

Pause

POST /api/v1/reports/schedules/{schedule_id}/pause
Authorization: Bearer {access_token}

Resume

POST /api/v1/reports/schedules/{schedule_id}/resume
Authorization: Bearer {access_token}

---

Delete Schedule

Request

DELETE /api/v1/reports/schedules/{schedule_id}
Authorization: Bearer {access_token}

---

Report Templates

List Templates

GET /api/v1/reports/templates
Authorization: Bearer {access_token}

Response

{
  "templates": [
    {
      "id": "template-sales",
      "name": "Sales Summary",
      "type": "sales_summary",
      "description": "Daily sales with category breakdown",
      "sections": [
        "summary",
        "hourly_breakdown",
        "category_breakdown",
        "payment_methods",
        "comparisons"
      ],
      "available_options": [
        "include_comparisons",
        "include_tips",
        "include_discounts"
      ]
    }
  ]
}

---

Custom Report Builder

Create Custom Report

POST /api/v1/reports/custom
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Custom Sales by Server",
  "location_ids": ["loc-xyz789"],
  "start_date": "2026-01-01",
  "end_date": "2026-01-18",
  "metrics": [
    "gross_sales",
    "net_sales",
    "order_count",
    "avg_ticket",
    "tips"
  ],
  "dimensions": [
    "server",
    "day_of_week"
  ],
  "filters": [
    {"field": "order_type", "operator": "in", "values": ["dine_in"]}
  ],
  "sort": [
    {"field": "gross_sales", "direction": "desc"}
  ],
  "format": "xlsx"
}

---

Share Report

Create Share Link

POST /api/v1/reports/{report_id}/share
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "expires_in_days": 7,
  "password_protected": true,
  "password": "secure123"
}

Response

{
  "share_url": "https://reports.olympuscloud.ai/shared/xyz789",
  "expires_at": "2026-01-25T12:00:00Z",
  "password_protected": true
}

Email Report

POST /api/v1/reports/{report_id}/email
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "recipients": [
    {"email": "manager@restaurant.com", "name": "John Manager"}
  ],
  "subject": "Weekly Sales Report",
  "message": "Please find attached the weekly sales report."
}

---

Report Data (JSON)

Get report data as JSON for custom visualization.

Request

GET /api/v1/reports/{report_id}/data
Authorization: Bearer {access_token}

Response

{
  "report_id": "report-abc123",
  "type": "sales_summary",
  "data": {
    "summary": {
      "gross_sales": 145000.00,
      "discounts": 4350.00,
      "refunds": 1250.00,
      "net_sales": 139400.00
    },
    "by_day": [
      {"date": "2026-01-01", "net_sales": 7500.00},
      {"date": "2026-01-02", "net_sales": 8200.00}
    ],
    "by_category": [
      {"category": "Entrees", "net_sales": 65000.00},
      {"category": "Beverages", "net_sales": 35000.00}
    ]
  }
}

---

Error Responses

Report Not Found (404)

{
  "error": {
    "code": "REPORT_NOT_FOUND",
    "message": "Report does not exist or has expired"
  }
}

Report Generation Failed (500)

{
  "error": {
    "code": "REPORT_GENERATION_FAILED",
    "message": "Failed to generate report",
    "details": "Insufficient data for the specified period"
  }
}

---

Related Documentation

• Dashboard API - Real-time metrics
• AI Insights - AI-powered analytics
• Exports Guide - Accounting exports