API Documentation

The HCSS Events Platform API uses OpenAPI 3.0 for API specification and Scalar UI for interactive documentation.

Accessing API Docs

Local Development

Once the backend is running (dotnet run from src/HCSS.EventsCore.WebApi):

Interface	URL	Purpose
Scalar UI	http://localhost:5234/scalar/v1	Interactive API explorer (recommended)
OpenAPI JSON	http://localhost:5234/swagger/v1/swagger.json	Raw spec for Postman/Insomnia import

Production

API documentation is only available in the Development environment for security reasons. For production API reference, use this documentation site.

Authentication

Most API endpoints require JWT Bearer authentication.

Getting a Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "your-email@example.com",
  "password": "your-password"
}

The response includes a token field. Use it in subsequent requests:

Authorization: Bearer <your-token>

Using Authentication in Scalar UI

1. Click the Authorize button in Scalar UI
2. Enter Bearer <your-token> in the authorization field
3. All subsequent requests will include the token

API Versioning

The API uses URL-based versioning:

/api/v1/events
/api/v1/caregivers

Current version: v1

Common Patterns

List Endpoints

List endpoints support pagination, filtering, and sorting:

GET /api/v1/events?page=1&pageSize=25&sortBy=name&sortDirection=asc

CRUD Operations

Method	Status Code	Description
GET /resources	200	List resources
GET /resources/{id}	200	Get single resource
POST /resources	201	Create resource
PUT /resources/{id}	200	Update resource
DELETE /resources/{id}	204	Delete resource

Error Responses

Errors follow RFC 7807 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "Name": ["The Name field is required."]
  }
}

Key API Modules

Module	Base Path	Endpoints
Authentication	/api/auth	Login, register, refresh, MFA
Events	/api/v1/events	CRUD, status management
Caregivers	/api/v1/caregivers	CRUD, import, export
Candidates	/api/v1/events/{id}/candidates	Pool management
Assignments	/api/v1/assignments	CRUD, bulk operations
Surveys	/api/v1/surveys	Templates, campaigns, responses
Travel	/api/v1/travel	Booking, itineraries
Compliance	/api/v1/compliance	Templates, packets, audit
Users	/api/v1/users	User management
Analytics	/api/v1/analytics	Reports, dashboards