Reports API
Fast access to the data that matters
1 · Quick overview

What it does

  • Pull any report on demand from your own applications.
  • One simple security rule – a single Bearer token issued by your app.
  • Standards all the way down – OpenAPI 3.1, pure JSON.
  • Built-in pagination for easy use of long lists.
  • Clear error codes instead of cryptic messages.

Why it helps you

  • No waiting: all your connected systems have 24/7 access.
  • Your team keeps full control; no separate sign-in or extra passwords.
  • Works with every modern language, framework, or BI tool.
  • Snappy UIs even with thousands of reports.
  • Faster debugging, fewer support tickets.
2 · Deep Dive
Base URL
				
					https://frontend.local/api
Auth
				
					Authorization: Bearer <FRONTEND_PROVIDED_TOKEN>
The API trusts whatever JWT your frontend issues. No server-side expiry / refresh logic here, so you decide token lifetime and rotation strategy.
2.1 · Endpoints
Verb & PathPurposeSuccessCommon errors
GET /reports/{id} Fetch the full JSON payload for one report.200→{ data: {…} }401 Unauthenticated, 404 Not found
GET /reports?page=1&per_page=25List reports (paginated).200 → { data: [ … ], meta: { page, per_page, total } }401 Unauthenticated

All other paths inherit the BearerAuth security scheme as defined in the OpenAPI 3.1 spec (see components.securitySchemes.BearerAuth).

2.2 · response shape 
				
					{
  "data": {
    "id": "abc123",
    "title": "NorthPoly P5508",
    "created_at": "2025-07-09T08:15:30Z",
    "data": { /* arbitrary nested KPI structure */ }
  }
}
On list calls you also get:
				
					"meta": {
  "page": 2,
  "per_page": 25,
  "total": 100
}
2.3 · Schema reference

ReportTransformer (excerpt)

FieldTypeNotes
idstringPrimary key
titlestringHuman-readable title
created_atstring (data-time)ISO-8601
dataobjectYour custom metrics
2.4 · Error catalogue
StatusBody
401{"message":"Unauthenticated"}
404{"error":{"code":"not_found","message":"Report not found"}}
Validation{ "message": "Validation error", "errors": { field: ["msg"] } }
2.5 · Sample Calls

Shell (cURL) 

				
					curl -X GET "https://frontend.local/api/reports?page=2&per_page=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

JavaScript (Fetch) 

				
					const res = await fetch("https://frontend.local/api/reports/abc123", {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
});
if (!res.ok) throw new Error(res.statusText);
const { data } = await res.json();
3 · Why engineers like it
  • Drop-in friendly: Works with Axios, Fetch, Postman, or any OpenAPI-aware client out of the box
  • Predictable footprint: Only two endpoints to remember; everything else is pagination or path params
  • Typed everywhere: The OpenAPI 3.1 spec lets you auto-generate TypeScript interfaces or PHP DTOs in seconds
  • Zero lock-in: Pure HTTP+JSON means you can migrate or extend without rewriting downstream consumers