API reference
Route-by-route reference for all 30 Next.js API handlers
The API is the server boundary of ROUNDTABLE. A browser page and an external internal tool should receive the same authentication, validation, database, and audit behavior because both call the same route handler. Every response is JSON unless the endpoint is a file export or file download.
Conventions
| Convention | Meaning |
|---|---|
{ data: ... } | Successful JSON response. |
{ error: "..." } | Generic client-safe error. |
| 401 | No acceptable session. |
| 403 | Session exists but role or scope is insufficient. |
| 404 | Record or file not found. |
| 409 | Duplicate or conflicting state. |
| 400 | Zod or request validation failed. |
| 500 | Unexpected server/storage failure; details remain in server logs. |
JSON examples use seeded names such as Pelagic Dynamics and NAVSEA. IDs are placeholders because Prisma generates cuid identifiers per database.
Complete route inventory
| Area | Route handlers |
|---|---|
| Analytics | pageview collection |
| Auth | /api/auth/[...nextauth] |
| Account | /api/account/password |
| Portal | announcements, calls, profile, register, submissions, submission file |
| Government | admin commands (list/create), command item, parent reassignment, admin users, announcements, calls, engagements, engagement notes, organization dialogue/status |
| Notifications | list, read, reroute, settings, unread count |
| Search | global search |
| Export | all JSON, entity CSV, engagements iCalendar |
The area pages below document all 30 route.ts files, including methods, authentication, validated fields, examples, response shapes, and failure cases.
One-row-per-handler coverage
| # | Handler path | Documented area |
|---|---|---|
| 1 | /api/auth/[...nextauth] | Auth |
| 2 | /api/account/password | Account |
| 3 | /api/analytics/pageview | Analytics |
| 4 | /api/export/all | Export |
| 5 | /api/export/csv | Export |
| 6 | /api/export/engagements.ics | Export |
| 7 | /api/gov/admin/commands | Government |
| 8 | /api/gov/admin/commands/[id] | Government |
| 9 | /api/gov/admin/commands/[id]/parent | Government |
| 10 | /api/gov/admin/users | Government |
| 11 | /api/gov/announcements | Government |
| 12 | /api/gov/calls | Government |
| 13 | /api/gov/calls/[id] | Government |
| 14 | /api/gov/engagements | Government |
| 15 | /api/gov/engagements/[id] | Government |
| 16 | /api/gov/engagements/[id]/notes | Government |
| 17 | /api/gov/organizations/[id]/dialogue | Government |
| 18 | /api/gov/organizations/[id]/status | Government |
| 19 | /api/notifications | Notifications |
| 20 | /api/notifications/read | Notifications |
| 21 | /api/notifications/reroute | Notifications |
| 22 | /api/notifications/settings | Notifications |
| 23 | /api/notifications/unread-count | Notifications |
| 24 | /api/portal/announcements | Portal |
| 25 | /api/portal/calls | Portal |
| 26 | /api/portal/profile | Portal |
| 27 | /api/portal/register | Portal |
| 28 | /api/portal/submissions | Portal |
| 29 | /api/portal/submissions/[id]/file | Portal |
| 30 | /api/search | Search |
The number above counts route files, not HTTP methods. For example, the command item handler has GET, PATCH, and DELETE but remains one route.ts handler path in the repository inventory.
Calling from another service
An internal caller should preserve the same cookies or approved session mechanism used by the browser, send the route's documented content type, and treat status codes as the primary contract. Do not send a client-controlled role or organization ID as proof of authority. Use server-side credentials and a reviewed integration boundary if a future service-to-service caller is added.
Status-code interpretation
| Status | First question |
|---|---|
| 200 | Did the response shape match the requested method and did the user have the intended scope? |
| 201 | Was the record created, and did any asynchronous or best-effort side effect also run? |
| 400 | Which field, query, multipart part, enum, date, or file signature failed validation? |
| 401 | Is there a session cookie, and is it addressed to the current origin? |
| 403 | Is the account the wrong audience, role, command scope, or export tier? |
| 404 | Is the ID valid and does the current scope permit the route to reveal its existence? |
| 409 | Is there a uniqueness, hierarchy-cycle, or serialization conflict? |
| 500 | Check server logs and backing services; do not expose internal exception text to clients. |
The endpoint pages pair these codes with route-specific examples. This table is a debugging orientation, not permission to assume that every handler returns every code.
When documenting a new handler, add its route-file path to the inventory and add at least one request/response example to the relevant area page. Keep method overloads together when one route.ts implements several methods.
For source-code drift checks, compare this inventory with find src/app/api -name route.ts after adding or removing handlers.
The current inventory has 30 route files, 15 Prisma models, and 9 Prisma enums. Re-derive rather than trusting these numbers when they matter: find src/app/api -name route.ts | wc -l, grep -c '^model ' prisma/schema.prisma, and grep -c '^enum ' prisma/schema.prisma in the application repository.
Review this page whenever a route is added, removed, or split so the beginner-facing map remains complete.