---
spec: agent-feature
status: ready
owner: feature-pipeline-agent
related-routes:
files:
  - src/api/v2/projects/files/files.routes.ts
  - src/api/v2/projects/files/files.controller.ts
  - src/services/files.service.ts
---

# agent-feature

## Goal

Add a read-only API2 endpoint GET /api/v2/projects/{projectId}/files/biggest that returns
the full file metadata for the largest non-soft-deleted file (by FileSizeBytes) in a project,
returning 200 with null body when none exist and 404 when the project does not exist. Backed
by a new fn_GetBiggestFile function; no schema changes.


## Behavior changes

- GET /api/v2/projects/{projectId}/files/biggest

## Acceptance criteria

- [ ] The behavior described above is implemented on the listed files.
- [ ] Existing behavior is unchanged when the new feature is not exercised.
- [ ] Unit and (where observable) e2e tests cover the new behavior.

## Out of scope

- Returning a ranked/sorted list of files by size (only the single biggest is returned).
- Filtering biggest-file selection by file type, extension, or other attributes.
- Any changes to API1 services (hc-project, hc-iam, hc-bpm, hc-notification).
- Including BatchFile or UserFile rows; only xyz.FileReference is considered.

## Notes / open questions

- Generated by the feature pipeline from the approved architect plan. If any
  acceptance criterion is ambiguous, ask the human before implementing.