API Reference

KitaManager provides a REST API with interactive OpenAPI/Swagger documentation available at /swagger/index.html when running the application. All endpoints except login and token refresh require JWT authentication. Mutating requests (POST, PUT, DELETE) require a CSRF token via the X-CSRF-Token header.

Authentication

Login Example

curl -X POST http://localhost:8080/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "admin123"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Using the Token

Include the token in the Authorization header for all subsequent requests:

curl http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Organizations

Sections

All section endpoints are scoped to an organization: /api/v1/organizations/{orgId}/sections.

Employees

All employee endpoints are scoped to an organization: /api/v1/organizations/{orgId}/employees.

Employee Contracts

Nested under an employee: .../employees/{id}/contracts.

Children

All child endpoints are scoped to an organization: /api/v1/organizations/{orgId}/children.

Child Contracts

Nested under a child: .../children/{id}/contracts.

Child Attendance

Nested under a child: .../children/{id}/attendance.

Government Funding Rates

Global resource managed by superadmins.

Funding Periods

Nested under a funding rate: .../government-funding-rates/{id}/periods.

Funding Properties

Nested under a period: .../periods/{periodId}/properties.

Government Funding Bills

Scoped to an organization: /api/v1/organizations/{orgId}/government-funding-bills.

Pay Plans

Scoped to an organization: /api/v1/organizations/{orgId}/pay-plans.

Pay Plan Periods

Nested under a pay plan: .../pay-plans/{id}/periods.

Pay Plan Entries

Nested under a period: .../periods/{periodId}/entries.

Budget Items

Scoped to an organization: /api/v1/organizations/{orgId}/budget-items.

Budget Item Entries

Nested under a budget item: .../budget-items/{id}/entries.

Statistics

Scoped to an organization: /api/v1/organizations/{orgId}/statistics. All statistics endpoints require from and to query parameters specifying a date range (format: YYYY-MM-DD).

Users

Global user management endpoints.

Organization Users

Pagination

List endpoints support pagination via query parameters:

curl "http://localhost:8080/api/v1/organizations?page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "data": [],
  "total": 100,
  "page": 1,
  "limit": 10
}

Error Responses

Errors are returned with the appropriate HTTP status code and a JSON body:

{
  "error": "Description of the error"
}