API Reference

CaseSolo uses Next.js App Router route handlers under src/app/api. The public developer API is exposed through the OpenAPI route, while most product routes are authenticated firm-scoped JSON endpoints.

Entry Points

• Swagger UI: /api-docs
• OpenAPI JSON: /api/docs/openapi
• Public developer portal registry: src/lib/developer-portal/registry.ts
• API key management: /api/settings/api-keys
• API usage reporting: /api/settings/api-usage
• Connector health aliases: /api/connectors, /api/integrations/health

Route Handler Contract

Every authenticated route should follow this shape:

1. Import NextRequest, NextResponse, and getCurrentUser.
2. Call const ctx = await getCurrentUser(request.headers).
3. Return 401 when ctx is missing.
4. Enforce role checks for admin-only routes.
5. Scope database reads and writes by ctx.firmId.
6. Use Prisma select clauses to avoid leaking unrelated fields.
7. Use noCacheHeaders() for sensitive authenticated GET responses.
8. Return JSON objects with stable keys consumed by the frontend and tests.

Response Patterns

Use consistent status codes:

• 200: successful read or action.
• 201: successful creation when the route creates persisted data.
• 400: invalid request payload or unsupported action.
• 401: unauthenticated.
• 403: authenticated but insufficient permission.
• 404: tenant-scoped resource not found.
• 409: duplicate or state conflict.
• 500: unexpected server error, with secret-safe logging.

Do not include API keys, OAuth tokens, refresh tokens, private URLs with signed query strings, or raw provider secrets in JSON responses. Return boolean readiness, hostnames, credential references, or redacted labels instead.

Mutations

For create, update, and delete routes:

• Validate required fields before database calls.
• Prefer Zod or explicit narrowing from unknown.
• Include firmId in where clauses or use updateMany/deleteMany when a

tenant-safe mutation should not throw on cross-firm records.

• Emit activity or audit records for security-sensitive actions.
• Return enough data for the caller to update state without a second fetch.

Public API Keys

Developer API keys are scoped. Any route reachable by external API keys must validate:

• Key hash, not raw key storage.
• Active status and expiration.
• Firm ownership.
• Explicit scope for the requested operation.
• Rate-limit and usage accounting.

OpenAPI Updates

When adding a public endpoint:

1. Update the developer portal registry or OpenAPI source.
2. Include authentication requirements and scope names.
3. Add examples for success and common failures.
4. Add route tests that call the handler directly with NextRequest.
5. Confirm /api/docs/openapi stays valid.

Testing API Routes

Route tests live in src/__tests__/api. Prefer direct handler calls:

const request = new NextRequest('http://localhost:3000/api/example', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ action: 'preview' }),
})

const response = await POST(request)
const payload = await response.json()

Mock getCurrentUser and Prisma through src/__tests__/helpers/mocks.ts. Always include at least one authorization test for protected routes.