API Reference

Complete reference for all GrydReports REST API endpoints.

Reports

List Available Reports

Returns all registered report templates with their metadata, supported formats, and parameters.

GET /api/v1/reports

Response 200 OK:

[
  {
    "templateId": "monthly-sales",
    "displayName": "Monthly Sales Report",
    "description": "Summarizes sales by period",
    "supportedFormats": [1, 2, 3],
    "parameters": [
      {
        "name": "month",
        "displayName": "Month",
        "valueType": "int",
        "required": true,
        "defaultValue": null,
        "allowedValues": null,
        "description": null
      }
    ],
    "isGlobal": false,
    "version": 1
  }
]

---

Get Execution History

Paginated list of report executions with filters.

GET /api/v1/reports/history?templateId=monthly-sales&status=3&format=1&fromDate=2026-01-01&toDate=2026-02-28&pageNumber=1&pageSize=20

Parameter	Type	Required	Default	Description
templateId	string	No	—	Filter by template ID
status	int	No	—	Filter by ReportStatus enum value
format	int	No	—	Filter by ReportFormat enum value
fromDate	DateTime	No	—	Start of date range
toDate	DateTime	No	—	End of date range
pageNumber	int	No	1	Page number
pageSize	int	No	20	Page size

Response 200 OK:

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "templateId": "monthly-sales",
      "reportName": "Sales Report - January 2026",
      "format": 1,
      "status": 3,
      "fileSizeBytes": 245760,
      "createdAt": "2026-01-15T10:00:00Z",
      "completedAt": "2026-01-15T10:00:02Z"
    }
  ],
  "totalCount": 42,
  "pageNumber": 1,
  "pageSize": 20,
  "totalPages": 3,
  "hasNext": true,
  "hasPrevious": false
}

---

Get Execution by ID

Detailed information about a specific report execution.

GET /api/v1/reports/{id}

Response 200 OK:

{
  "id": "f47ac10b-...",
  "templateId": "monthly-sales",
  "reportName": "Sales Report - January 2026",
  "format": 1,
  "status": 3,
  "parametersJson": "{\"month\":1,\"year\":2026}",
  "storedFileId": "0b8e2f51-7c3d-4e6a-9f10-2a4b6c8d0e12",
  "fileName": "monthly-sales-2026-01.pdf",
  "contentType": "application/pdf",
  "fileSizeBytes": 245760,
  "generationDuration": "00:00:02.341",
  "errorMessage": null,
  "startedAt": "2026-01-15T10:00:00Z",
  "completedAt": "2026-01-15T10:00:02Z",
  "requestedBy": "a1b2c3d4-...",
  "scheduleId": null,
  "downloadCount": 3,
  "expiresAt": "2026-04-15T10:00:00Z",
  "createdAt": "2026-01-15T10:00:00Z"
}

Error 404 Not Found — report ID does not exist.

---

Generate Report (Sync)

Generates a report synchronously and returns the result with download info.

POST /api/v1/reports/generate
Content-Type: application/json

Request Body:

{
  "templateId": "monthly-sales",
  "format": 1,
  "parameters": {
    "month": 1,
    "year": 2026
  },
  "requestedBy": "user@company.com"
}

Field	Type	Required	Description
templateId	string	Yes	Template identifier
format	int	Yes	ReportFormat enum (1=PDF, 2=Excel, 3=CSV, 4=HTML)
parameters	object?	No	Report parameters
requestedBy	string?	No	Requester identifier

Response 201 Created:

{
  "id": "f47ac10b-...",
  "templateId": "monthly-sales",
  "reportName": "Sales Report",
  "format": 1,
  "status": 3,
  "fileName": "monthly-sales-2026-01.pdf",
  "fileSizeBytes": 245760,
  "storedFileId": "0b8e2f51-7c3d-4e6a-9f10-2a4b6c8d0e12",
  "generationDuration": "00:00:02.341",
  "createdAt": "2026-02-19T10:30:00Z"
}

---

Generate Report (Async)

Queues a report for background generation with optional delivery.

POST /api/v1/reports/generate-async
Content-Type: application/json

Request Body:

{
  "templateId": "annual-financial",
  "format": 2,
  "parameters": { "year": 2025 },
  "delivery": {
    "method": 2,
    "recipients": ["cfo@company.com"],
    "emailSubject": "Annual Report 2025"
  },
  "requestedBy": "admin@company.com"
}

Field	Type	Required	Description
templateId	string	Yes	Template identifier
format	int	Yes	ReportFormat enum
parameters	object?	No	Report parameters
delivery	DeliveryOptions?	No	Delivery configuration
requestedBy	string?	No	Requester identifier

Response 202 Accepted — includes tracking ID for status polling.

---

Download Report

Issues a short-lived presigned URL to the generated report. Breaking change: this route used to stream the file; it now returns the URL and the caller fetches the file from storage.

GET /api/v1/reports/{id}/download

Response 200 OK:

{
  "url": "https://storage.example.com/…?X-Amz-Signature=…",
  "expiresAt": "2026-09-10T18:05:00Z"
}

A GET on url returns the file as application/octet-stream with Content-Disposition: attachment; filename*=UTF-8''…. The URL expires in minutes; request a new one instead of storing it.

Errors: 404 REPORT_NOT_FOUND; 409 REPORT_NOT_AVAILABLE (not completed); 409 FILE_NOT_AVAILABLE_CONFLICT (the file is still being verified — retry shortly); 409 FILE_PURGED_CONFLICT (retention already collected it).

---

Delete Report

Soft-deletes a report execution and releases its stored file; GrydFiles purges the file after the retention grace period.

DELETE /api/v1/reports/{id}

Response 204 No Content

Error 404 Not Found — report not found.

---

Schedules

List Schedules

Paginated list of report schedules with filters.

GET /api/v1/reports/schedules?templateId=daily-sales&isActive=true&pageNumber=1&pageSize=20

Parameter	Type	Required	Default
templateId	string	No	—
isActive	bool	No	—
pageNumber	int	No	1
pageSize	int	No	20

---

Get Schedule Details

GET /api/v1/reports/schedules/{id}

---

Create Schedule

POST /api/v1/reports/schedules
Content-Type: application/json

Request Body:

{
  "templateId": "daily-sales",
  "name": "Daily Sales Report",
  "cronExpression": "0 8 * * *",
  "format": 1,
  "parameters": { "region": "south" },
  "delivery": {
    "method": 2,
    "recipients": ["team@company.com"]
  },
  "description": "Daily report at 8 AM"
}

Response 201 Created

---

Update Schedule

PUT /api/v1/reports/schedules/{id}
Content-Type: application/json

Request Body (all fields optional):

{
  "name": "Updated Name",
  "cronExpression": "0 9 * * *",
  "format": 2,
  "parametersJson": "{\"region\":\"north\"}",
  "deliveryOptionsJson": "{\"method\":2,\"recipients\":[\"new@company.com\"]}",
  "description": "Updated description"
}

Response 204 No Content

---

Delete Schedule

DELETE /api/v1/reports/schedules/{id}

Response 204 No Content

---

Trigger Schedule

Execute a schedule immediately (out-of-cycle).

POST /api/v1/reports/schedules/{id}/trigger

Response 202 Accepted

---

Pause Schedule

POST /api/v1/reports/schedules/{id}/pause

Response 204 No Content

---

Resume Schedule

POST /api/v1/reports/schedules/{id}/resume

Response 204 No Content

---

Enums Reference

ReportFormat

Value	Name	Content-Type
1	Pdf	application/pdf
2	Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
3	Csv	text/csv
4	Html	text/html

ReportStatus

Value	Name	Description
1	Queued	Waiting for processing
2	Generating	Currently being generated
3	Completed	Generation successful
4	Failed	Generation failed
5	Delivered	Delivered to recipients
6	Cancelled	Cancelled by user

DeliveryMethod

Value	Name	Description
1	Download	Available for download
2	Email	Sent as email attachment
3	Storage	Copied to target path
4	Webhook	POST to webhook URL

Error Responses

All error responses follow RFC 7807 Problem Details format. The HTTP status code is determined by the ErrorCode suffix:

ErrorCode Suffix	HTTP Status
_NOT_FOUND	404
_ALREADY_EXISTS	409
_CONFLICT	409
_FORBIDDEN	403
_UNAUTHORIZED	401
_UNPROCESSABLE	422
(default)	400