Project Reports API

All endpoints require authentication and projects tool permissions. Routes are mounted under /api/projects.

Reports

List Reports

GET /api/projects/:id/reports

Permission: projects:view

Query parameters:

Param	Type	Description
`status`	string	Filter by report status
`limit`	number	Items per page (default: 20)
`page`	number	Page number (default: 1)

Response: { reports, total }

Get Latest Report

GET /api/projects/:id/reports/latest

Permission: projects:view

Response: { report } — null if no reports exist.

Generate Report

POST /api/projects/:id/reports/generate

Permission: projects:update

Generates a weekly report using AI. Pulls task progress, budget data, and other project context to produce report sections.

Body:

Field	Type	Required	Description
`week_ending`	string	No	Week ending date (defaults to current Friday)

Response: { report }

Get Report

GET /api/projects/:id/reports/:reportId

Permission: projects:view

Response: { report }

Update Report

PATCH /api/projects/:id/reports/:reportId

Permission: projects:update

Body: Any of the following fields:

Field	Type	Description
`section_summary`	string	Executive summary
`section_progress`	string	Progress/completed items
`section_in_progress`	string	Currently in progress
`section_next_week`	string	Planned for next week
`section_issues`	string	Issues and blockers
`section_budget`	string	Budget status
`subject_line`	string	Email subject line
`recipient_emails`	string[]	Recipient email addresses
`internal_notes`	string	Internal-only notes
`overall_status`	string	Overall project status indicator
`status`	string	Report status (e.g. `draft`, `sent`)

Response: { report }

Send Report

POST /api/projects/:id/reports/:reportId/send

Permission: projects:update

Sends the report via email to the configured recipients. Recipients can be set on the report itself or fall back to the project’s report settings.

Response: { report }

Preview Report HTML

GET /api/projects/:id/reports/:reportId/preview

Permission: projects:view

Returns the rendered HTML email as it would appear to recipients.

Response: { html }

Report Settings

Get Settings

GET /api/projects/:id/report-settings

Permission: projects:view

Response: { settings } — null if not configured.

Create/Replace Settings

POST /api/projects/:id/report-settings

Permission: projects:update

Uses upsert — creates settings if none exist, or replaces existing settings for the project.

Body:

Field	Type	Description
`recipient_emails`	string[]	Default recipient email addresses
`include_budget`	boolean	Include budget section (default: true)
`intro_text`	string	Custom intro text for report emails
`outro_text`	string	Custom outro text for report emails
`custom_section_labels`	object	Override default section labels
`auto_generate`	boolean	Enable automatic report generation

Response: { settings }

Patch Settings

PATCH /api/projects/:id/report-settings

Permission: projects:update

Partial update of report settings.

Body: Any of: recipient_emails, include_budget, intro_text, outro_text, custom_section_labels, auto_generate.

Response: { settings }

Reports Due

GET /api/projects/reports/due

Permission: projects:view

Returns active projects with auto_generate enabled that do not have a sent report for the current week. Results are scoped by access level:

Employee/Lead: only projects the user is a member of.
Manager: projects where the user is DM, owner, or a member.
Head/Executive: all projects.

Response:

{
  "projects": [
    {
      "id": "string",
      "name": "string",
      "company_name": "string",
      "dm_name": "string",
      "report_id": "string or null",
      "report_status": "string or null",
      "generated_at": "string or null"
    }
  ]
}