Export API

Exports contain government ledger data and are intentionally restricted. Only GOV_ADMIN and GOV_SYSTEM_ADMIN pass the export role gate. A command lead, POC, readonly user, or industry user receives 403 even if they can see some individual records elsewhere.

GET /api/export/all

Auth: GOV_ADMIN or GOV_SYSTEM_ADMIN; success: 200 JSON.

curl http://localhost:3000/api/export/all \
  -H 'cookie: next-auth.session-token=ADMIN_SESSION'

Example shape:

{"data":{"organizations":[{"id":"clx-pelagic","name":"Pelagic Dynamics","status":"ACTIVE"}],"submissions":[{"id":"clx-submission","organizationId":"clx-pelagic","title":"Autonomous UUV navigation","status":"ROUTED"}],"engagements":[{"id":"clx-engagement","title":"Pelagic Dynamics autonomy demo","organizationId":"clx-pelagic","commandId":"clx-niwcpac"}],"calls":[{"id":"clx-call","title":"Maritime AI for Predictive Maintenance","status":"OPEN"}]}}

The exact bundle includes the route's selected model fields. Errors: 401, 403, 500. The endpoint is not industry-safe and should be handled under approved data policy.

GET /api/export/csv

Auth: GOV_ADMIN or GOV_SYSTEM_ADMIN; success: 200 text/csv.

curl -OJ 'http://localhost:3000/api/export/csv?entity=engagements' \
  -H 'cookie: next-auth.session-token=ADMIN_SESSION'

The response has a CSV content type and download filename appropriate to the entity. An invalid or missing entity is 400; unauthenticated/unauthorized are 401/403; unexpected database or serialization errors are 500.

GET /api/export/engagements.ics

Auth: GOV_ADMIN or GOV_SYSTEM_ADMIN; success: 200 text/calendar.

curl -OJ http://localhost:3000/api/export/engagements.ics \
  -H 'cookie: next-auth.session-token=ADMIN_SESSION'

Each engagement becomes an iCalendar event with title, date, location, summary, and status. Errors: 401, 403, 500. This endpoint is useful for a government calendar workflow but does not create or modify engagement records.

Safe handling checklist

1. Verify the caller's role before generating a file.
2. Keep exports in approved storage.
3. Avoid sending a government export to an industry recipient.
4. Remove temporary downloads when the approved use ends.
5. Treat submission summaries and dialogue context as potentially sensitive even when the route is technically authorized.

Export response headers

The JSON route uses an application JSON response. CSV and iCalendar routes set download-oriented content types and content-disposition metadata so browsers can save the result. Consumers should not assume a JSON envelope for those file responses; parse them according to their declared media type.

Why command leads cannot export

A command lead may have legitimate access to its own command's operational work, but export is an enterprise-level capability. Restricting it to GOV_ADMIN and GOV_SYSTEM_ADMIN avoids turning a scoped view into a portable enterprise dataset. If a future requirement needs scoped export, it should add an explicit scoped format rather than weakening the current gate.

Consumer checklist

• Authenticate as an enterprise administrator before making the request.
• Preserve the response media type and filename.
• Treat every field as potentially sensitive operational data.
• Do not assume CSV and JSON contain identical columns.
• Parse iCalendar dates with a timezone-aware library.
• Check for an empty dataset before treating the download as a transport failure.
• Store the file only where the approved audience can access it.
• Delete temporary copies when the review or import is complete.