API reference
Ascendly’s backend is a FastAPI application. Interactive API documentation is generated automatically from route definitions and Pydantic schemas.
Interactive docs (Swagger UI)
On the staff network (or local development), open:
- Swagger UI:
/docs - ReDoc:
/redoc - OpenAPI JSON:
/openapi.json
Local development
When running the API locally on the default port:
| Resource | URL |
|---|---|
| Swagger UI | http://localhost:8000/docs |
| Health check | http://localhost:8000/health |
Production / staging
Production and staging base URLs depend on your organization’s deployment. Ask your system administrator for the API hostname, then append /docs.
Authentication
Most endpoints require a valid JWT from Google sign-in. Use the Authorize button in Swagger after obtaining a token from the web app, or call endpoints from the authenticated web client. Desktop clients also use refresh tokens — see Platform & admin § Desktop refresh tokens.
Base paths
| Prefix | Domain |
|---|---|
/v1/public | Unauthenticated app status (maintenance flag) |
/v1/auth | Google OAuth, JWT refresh, permissions, activity heartbeat |
/v1/scorecard | Scorecard CRUD, configurations, schedules, task delivery |
/v1/atw-entry-requests | Employee ATW submit; manager approve/reject |
/v1/dashboard | BSC rollups, cycle performance, sync jobs, finalize/reopen |
/v1/notifications | In-app inbox, delivery preferences |
/v1/system | Operational status (level 5) |
/v1/system/notifications | Notification type catalog, email test (level 5) |
/v1/system/email | Admin broadcast compose (level 5) |
/v1/employees | Directory CRUD, welcome email |
/v1/organization | Org tree (GET /tree) |
/v1/learning | Courses and enrollments |
Dashboard (notable routes)
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/dashboard/bsc/month-snapshot | Single-month BSC snapshot |
| GET | /v1/dashboard/bsc/available-months | Month picker options (BQ + entries + month reports) |
| GET | /v1/dashboard/bsc/performance | Full-cycle performance (cycle_id query) |
| GET | /v1/dashboard/bsc/comparison-access | Whether the current user can view Performance comparison |
| POST | /v1/dashboard/bsc/sync | Manual / rolling sync (level 5); async=true queues background job |
| GET | /v1/dashboard/bsc/sync-jobs/active | In-progress sync job for a month |
| GET | /v1/dashboard/bsc/sync-jobs/{job_id} | Poll sync/finalize job progress |
| POST | /v1/dashboard/bsc/refresh-employee-cycle | Re-sync one employee across a fiscal cycle (level 5) |
| POST | /v1/dashboard/bsc/finalize | Generate Final Report (background job) |
| POST | /v1/dashboard/bsc/reopen | Reopen finalized month (level 5) |
Public
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/public/app-status | Maintenance flag; optional Authorization: Bearer to check bypass access |
Auth & platform
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/auth/google | Exchange Google code for JWT (+ refresh token when client: desktop) |
| POST | /v1/auth/refresh | Rotate refresh token → new JWT + refresh token |
| POST | /v1/auth/logout | Revoke refresh token |
| GET | /v1/auth/permissions | Current user permissions |
| GET | /v1/auth/permissions/matrix | Full access-level matrix (level 5) |
| POST | /v1/auth/activity-heartbeat | Record active minute + client last active (client: web | desktop); visible-on-screen only |
| GET | /v1/auth/activity-summary | Self activity summary (today + 7-day rolling, split by client) |
| GET | /v1/employees/activity-export | Manager CSV: last login, last active (web/desktop/latest), active minutes |
| GET | /v1/system/status | Mongo, BQ, S3, worker health (level 5) |
| POST | /v1/system/email/send | Admin broadcast email (level 5) |
| POST | /v1/employees/welcome-email | Send welcome email to selected employees |
Organization
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/organization/tree | Clusters, departments, managers, members, and directory (includes hire_date on employee nodes) |
Guide: Organization.
ATW entry requests
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/atw-entry-requests | List (scope=mine | approval) |
| GET | /v1/atw-entry-requests/pending-count | Manager pending badge count |
| POST | /v1/atw-entry-requests | Submit (multipart + optional proof) |
| POST | /v1/atw-entry-requests/{id}/approve | Approve → creates ATW entry |
| POST | /v1/atw-entry-requests/{id}/reject | Reject with review note |
| DELETE | /v1/atw-entry-requests/{id} | Employee cancel pending request |
Detailed route lists, request bodies, and response schemas are in Swagger — they stay in sync with the codebase.
Related guides
- Scorecard — page-by-page API summary and collections
- User activity — heartbeat rules, last active, HR troubleshooting
- Platform & admin — sign-in domains, system status, admin email
- Notifications — inbox and delivery
- Dashboard overview — five dashboard pages
- Bonus qualification — manager gate matrix (
/dashboard/bsc-bonus) - BigQuery dashboard — dashboard read path and sync endpoints