API Reference¶

Interactive Documentation¶

When the application is running, interactive API documentation is available at:

Swagger UI: http://localhost:8485/api/docs

Authentication¶

All API endpoints (except /health and /api/auth/*) require authentication via session cookie.

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

{
    "email": "user@example.com",
    "password": "password"
}

GET /api/auth/sso/login     → Returns the Microsoft authorization URL
GET /api/auth/sso/callback  → Handles the OAuth callback from Microsoft

Logout¶

POST /api/auth/logout

Tenant API Routes¶

All tenant routes are prefixed with /t/{slug}/api/:

Projects¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/projects`	List all projects (with phases, subphases, assignments)
`POST`	`/t/{slug}/api/projects`	Create a project
`GET`	`/t/{slug}/api/projects/{id}`	Get project details with full hierarchy
`PUT`	`/t/{slug}/api/projects/{id}`	Update a project
`DELETE`	`/t/{slug}/api/projects/{id}`	Delete a project

Phases & Subphases¶

Method	Endpoint	Description
`POST`	`/t/{slug}/api/projects/{id}/phases`	Create a phase
`PUT`	`/t/{slug}/api/phases/{id}`	Update a phase (dates, name, dependencies)
`DELETE`	`/t/{slug}/api/phases/{id}`	Delete a phase
`PUT`	`/t/{slug}/api/projects/{id}/phases/reorder`	Reorder phases
`POST`	`/t/{slug}/api/phases/{id}/subphases`	Create a subphase
`PUT`	`/t/{slug}/api/subphases/{id}`	Update a subphase (dates, name, dependencies)
`DELETE`	`/t/{slug}/api/subphases/{id}`	Delete a subphase
`PUT`	`/t/{slug}/api/phases/{id}/subphases/reorder`	Reorder subphases

Staff¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/staff`	List all staff
`GET`	`/t/{slug}/api/staff/{id}`	Get a staff member
`GET`	`/t/{slug}/api/staff/{id}/availability`	Availability calculation

Staff endpoints are read-only — staff members are users and are created and managed via the /users endpoints.

Equipment¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/equipment`	List all equipment
`POST`	`/t/{slug}/api/equipment`	Create equipment item
`PUT`	`/t/{slug}/api/equipment/{id}`	Update equipment item
`DELETE`	`/t/{slug}/api/equipment/{id}`	Delete equipment item
`GET`	`/t/{slug}/api/equipment/{id}/availability?startDate=&endDate=`	Per-day availability for a date range

Equipment Blocks (Maintenance / Out-of-service)¶

Block periods mark equipment as unavailable for booking. See Equipment Booking — Maintenance Blocks for the user-facing behaviour.

Method	Endpoint	Description
`GET`	`/t/{slug}/api/equipment-blocks?siteId=&equipmentId=`	List equipment blocks (optional filters)
`GET`	`/t/{slug}/api/equipment/{id}/blocks`	List blocks for one equipment item
`POST`	`/t/{slug}/api/equipment-blocks`	Create a block (admin/superuser)
`PUT`	`/t/{slug}/api/equipment-blocks/{id}`	Update a block
`DELETE`	`/t/{slug}/api/equipment-blocks/{id}`	Delete a block

Assignments¶

Method	Endpoint	Description
`POST`	`/t/{slug}/api/projects/{id}/staff`	Assign staff at project level
`PUT` / `DELETE`	`/t/{slug}/api/assignments/{id}`	Update / remove project-level assignment
`POST`	`/t/{slug}/api/phases/{id}/staff`	Assign staff at phase level
`PUT` / `DELETE`	`/t/{slug}/api/phase-staff/{id}`	Update / remove phase-level assignment
`POST`	`/t/{slug}/api/subphases/{id}/staff`	Assign staff at subphase level
`PUT` / `DELETE`	`/t/{slug}/api/subphase-staff/{id}`	Update / remove subphase-level assignment
`POST`	`/t/{slug}/api/projects/{id}/equipment`	Book equipment on a project
`PUT` / `DELETE`	`/t/{slug}/api/equipment-assignments/{id}`	Update / remove equipment booking

Vacations¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/vacations`	List all vacations
`POST`	`/t/{slug}/api/vacations`	Create a vacation
`PUT`	`/t/{slug}/api/vacations/{id}`	Update a vacation
`DELETE`	`/t/{slug}/api/vacations/{id}`	Delete a vacation

Equipment Types¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/equipment-types`	List all equipment types
`PUT`	`/t/{slug}/api/equipment-types/{old_type}`	Rename an equipment type
`DELETE`	`/t/{slug}/api/equipment-types/{type_name}`	Delete an equipment type

Tags¶

Project tags are colored labels shared across all projects in the instance. See Gantt Charts — Tags for the user-facing behaviour. To attach or detach tags from a project, send a tag_ids array in the project PUT payload.

Method	Endpoint	Description
`GET`	`/t/{slug}/api/tags`	List all tags (with project usage counts)
`POST`	`/t/{slug}/api/tags`	Create a tag (admin/superuser)
`PUT`	`/t/{slug}/api/tags/{id}`	Update a tag's name or color (admin/superuser)
`DELETE`	`/t/{slug}/api/tags/{id}`	Delete a tag from every project (admin/superuser)

Import & Export¶

Method	Endpoint	Description
`POST`	`/t/{slug}/api/import/project`	Import a project from CSV / XML (multipart upload)
`POST`	`/t/{slug}/api/import/mpp`	Import a project from Microsoft Project (`.mpp`/`.mpt`/`.mpx`) — requires Java
`GET`	`/t/{slug}/api/import/mpp/test`	Diagnostic — verify Java/MPP toolchain is available
`GET` / `POST`	`/t/{slug}/api/export/csv/{id}`	Export a single project as CSV
`POST`	`/t/{slug}/api/export/mpp/{id}`	Export a single project for Microsoft Project
`GET`	`/t/{slug}/api/export/site/{site_id}/excel`	Export the full site (multi-sheet `.xlsx`) — admin/superuser only

Custom Columns¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/custom-columns`	List custom column definitions
`POST`	`/t/{slug}/api/custom-columns`	Create a custom column
`PATCH`	`/t/{slug}/api/custom-columns/{id}`	Update a custom column
`DELETE`	`/t/{slug}/api/custom-columns/{id}`	Delete a custom column
`PATCH`	`/t/{slug}/api/custom-columns/reorder`	Reorder columns
`PUT`	`/t/{slug}/api/custom-columns/values`	Write a column value (`/values/batch` for bulk)

Real-Time Collaboration¶

Method	Endpoint	Description
`WS`	`/t/{slug}/ws`	WebSocket for real-time updates and presence

Presence (who is online, who is viewing a project) is handled entirely over the WebSocket connection — there are no HTTP presence endpoints.

Other Endpoints¶

Method	Endpoint	Description
`GET`	`/t/{slug}/api/sites`	List sites
`POST`	`/t/{slug}/api/sites`	Create a site
`PUT`	`/t/{slug}/api/sites/{id}`	Update a site
`GET`	`/t/{slug}/api/skills`	List skills
`POST`	`/t/{slug}/api/skills`	Create a skill
`PUT`	`/t/{slug}/api/skills/{id}`	Update a skill
`DELETE`	`/t/{slug}/api/skills/{id}`	Delete a skill
`GET`	`/t/{slug}/api/settings`	Get instance settings
`PUT`	`/t/{slug}/api/settings`	Update settings
`GET`	`/t/{slug}/api/users`	List users
`POST`	`/t/{slug}/api/users`	Create a user
`PUT`	`/t/{slug}/api/users/{id}`	Update a user
`DELETE`	`/t/{slug}/api/users/{id}`	Delete a user
`GET`	`/t/{slug}/api/predefined-phases`	List predefined phases
`POST`	`/t/{slug}/api/predefined-phases`	Create a predefined phase
`PUT`	`/t/{slug}/api/predefined-phases/{id}`	Update a predefined phase
`DELETE`	`/t/{slug}/api/predefined-phases/{id}`	Delete a predefined phase
`GET`	`/t/{slug}/api/notes`	List notes
`POST`	`/t/{slug}/api/notes`	Create a note
`DELETE`	`/t/{slug}/api/notes/{id}`	Delete a note

Admin API Routes¶

Admin routes are at /api/admin/:

Method	Endpoint	Description
`POST`	`/api/admin/auth/login`	Admin login
`GET`	`/api/admin/tenants`	List tenants
`POST`	`/api/admin/tenants`	Create tenant
`PUT`	`/api/admin/tenants/{id}`	Update tenant
`DELETE`	`/api/admin/tenants/{id}`	Delete tenant
`GET`	`/api/admin/organizations`	List organizations
`POST`	`/api/admin/organizations`	Create organization
`GET`	`/api/admin/users`	List admin users
`GET`	`/api/admin/stats`	System statistics

Request & Response Examples¶

Create a Project¶

POST /t/{slug}/api/projects
Content-Type: application/json

{
    "name": "New Drug Formulation",
    "start_date": "2026-05-01",
    "end_date": "2026-09-30",
    "confirmed": true,
    "site_id": 1,
    "project_manager": "Dr. Smith",
    "customer": "PharmaCorp",
    "predefined_phase_ids": [1, 2, 3]
}

Update a Phase (with Dependencies)¶

PUT /t/{slug}/api/phases/42
Content-Type: application/json

{
    "name": "Analytical Development",
    "start_date": "2026-06-01",
    "end_date": "2026-07-15",
    "dependencies": [
        {"id": 41, "type": "FS"},
        {"id": 38, "type": "SS"}
    ]
}

Health Check¶

GET /health
GET /api/health

Both endpoints return identical content. They require no authentication and are safe for load-balancer probes.

{
    "status": "ok",
    "mode": "multi-tenant",
    "version": "1.0.0",
    "backend": "python-fastapi",
    "default_tenant": "demo",
    "timestamp": "2026-05-06T12:34:56.789012",
    "database": "connected"
}

The version field is read at startup from the repo-root /VERSION file (see Contributing — Versioning & Changelog). If the database is unreachable the response is still returned with status: "ok" but database contains an error: ... string — useful for distinguishing process-level failure from DB-level failure in monitoring.