API Overview

The Noumaris backend API is built with FastAPI and provides 23+ REST endpoints for managing institutions, residents, permissions, and clinical documentation.

Base URLs

• Production: https://api.noumaris.com
• Development: http://localhost:8000

Authentication

All endpoints (except /invite/* public endpoints) require JWT authentication via Keycloak.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Getting a Token

1. Login via Keycloak at your organization's login page
2. Extract JWT token from session
3. Include token in Authorization header for all API requests

API Categories

Superadmin Endpoints (8 endpoints)

Required Role: superadmin

• Institution management (create, update, list, suspend)
• Feature grants (institution-level)
• System analytics
• Admin creation

Institution Admin Endpoints (11 endpoints)

Required Role: institution_admin

• Resident management (invite, update, list)
• Permission management (grant, revoke, bulk operations)
• Usage metrics
• Audit log

Invitation Endpoints (3 endpoints)

Public - No authentication required

• Validate invitation token
• Accept invitation
• Token expiry handling

Clinical Documentation Endpoints

Required Role: user (authenticated)

• Document creation
• Audio transcription (WebSocket)
• Note generation (Claude AI)
• Template management

Interactive Documentation

FastAPI provides auto-generated interactive API documentation:

• Swagger UI: /docs - Try out endpoints directly
• ReDoc: /redoc - Alternative documentation view
• OpenAPI JSON: /openapi.json - Machine-readable schema

Rate Limiting

Endpoint Type	Limit	Window
Health checks	100 requests	1 minute
Standard endpoints	50 requests	1 minute
Admin endpoints	50 requests	1 minute
WebSocket connections	3 concurrent	Per user

Error Codes

Code	Meaning	Common Causes
400	Bad Request	Invalid input, capacity limits exceeded
401	Unauthorized	Missing or invalid JWT token
403	Forbidden	Insufficient permissions for action
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate record
422	Validation Error	Pydantic validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Complete API Reference

See API Endpoints → for complete documentation of all 23 endpoints with request/response examples.

Postman Collection

A Postman collection is available for testing all endpoints. Download from the backend repository:

backend/postman/Noumaris_API_Collection.json

Setup Instructions

1. Import collection into Postman
2. Set environment variables:
   • base_url: Backend URL
   • jwt_token: Your JWT token from Keycloak
   • institution_id: Test institution ID
3. Run requests in order (authentication first)