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. The access token lasts 7 days (JWT_EXPIRE_MINUTES=10080). 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 a 365-day refresh token — see Platform & admin § Session length.
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, weekly kudos |
/v1/atw-entry-requests | Employee ATW submit; manager approve/reject |
/v1/dashboard | News, 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/system/teams | Teams channel connection, test, compose, post history (level 5) |
/v1/system/visibility | Page visibility catalog and toggles (level 5) |
/v1/visibility | Effective page visibility for clients |
/v1/employees | Directory CRUD, welcome email, create requests |
/v1/organization | Org tree (GET /tree) |
/v1/learning | Modules, units, player, enrollments, file upload |
/v1/assistant | Read-only explain/rank capabilities (no chat UI) |
Dashboard (notable routes)
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/dashboard/news | News stories payload (BSC Passers, etc.) |
| GET | /v1/dashboard/news/bonus-qualifiers | Company-wide bonus-qualified employees for a finalized month |
| GET | /v1/dashboard/news/my-birthday | Whether the signed-in employee is a celebrant today |
| 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/dev-login | Development-only email login helper (requires env flag + allowlisted email) |
| 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) |
| GET | /v1/system/teams/connection | Teams webhook connection status (level 5; URL masked) |
| PUT | /v1/system/teams/connection | Save Teams Workflows webhook URL (level 5) |
| PATCH | /v1/system/teams/connection | Enable or disable automated Teams posts (level 5; default off) |
| DELETE | /v1/system/teams/connection | Disconnect Teams webhook (level 5) |
| POST | /v1/system/teams/test | Send a test Adaptive Card (level 5) |
| POST | /v1/system/teams/compose | Post subject + body to the channel (level 5) |
| GET | /v1/system/teams/posts | Recent channel posts and failures (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 |
Assistant
Users type free-form questions in the Ask Nella panel. The model may call scoped tools; it cannot query Mongo/BigQuery itself or change data. Set ASSISTANT_CHAT_ENABLED=false on the API to hide the chip and refuse chat. ASSISTANT_CAPABILITIES_ENABLED=false also disables explain/rank tools. Chat needs at least one of ASSISTANT_LLM_API_KEY / OPENAI_API_KEY, GEMINI_API_KEY, or Vertex Grok (GCP_PROJECT_ID). Super admins choose the active model at /system/nella (default try-order Grok 4.6 → Gemini 3.7 Flash → OpenAI).
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/assistant/status | Whether chat is available for this environment |
| POST | /v1/assistant/chat | Free-form prompt; server-side tool loop; saves into the asker's thread |
| GET | /v1/assistant/threads | List the asker's saved chats (pinned first) |
| GET | /v1/assistant/threads/{id} | Load one owned chat |
| PATCH | /v1/assistant/threads/{id} | Rename or pin/unpin an owned chat |
| DELETE | /v1/assistant/threads/{id} | Soft-delete one owned chat (hidden from the asker; quality review can still open it until the 90-day TTL) |
| GET | /v1/assistant/capabilities | Internal tool catalog (not the user UI) |
| GET | /v1/assistant/explain/tenure | Internal tenure tool |
| GET | /v1/assistant/rank/employees | Internal ranking tool |
| GET | /v1/assistant/summarize/bsc | Internal month BSC summary |
| GET | /v1/assistant/explain/bonus | Internal bonus-gate explain |
| GET | /v1/assistant/explain/scheduled-locking | Internal live weekly/monthly lock settings |
Guide citation paths (/guide/…) are pages on the VitePress docs site (VITE_DOCS_URL), not routes in the web app.
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 — News + five BSC score pages
- News — BSC Passers, birthdays
- Bonus qualification — manager gate matrix (
/dashboard/bsc-bonus) - Learning — modules and enrollments
- Assistant plan —
/v1/assistant/chat - Weekly Kudos —
/v1/scorecard/weekly-kudos - BigQuery dashboard — dashboard read path and sync endpoints