API Reference¶

Verified against implementation on 2026-05-17.

Contract source of truth¶

1. src/app/api/*
2. src/app/schemas/*
3. runtime GET /openapi.json (development/debug mode)
4. shared error contracts in src/app/api/contracts.py

Important clarification¶

GitPulse does not use a JWT login endpoint such as /api/v1/auth/login.

Authentication uses three modes:

1. Dashboard: GitLab OAuth + session cookie.
2. API: static bearer token (TEACHER_API_TOKEN) or dashboard session.
3. Webhook endpoint: X-Gitlab-Token.

Base prefixes¶

Health and ops endpoints¶

• GET /health
• GET /health/live
• GET /health/ready
• GET /metrics

Example:

1
2

curl http://localhost:8000/health
curl http://localhost:8000/metrics

API authentication examples¶

Bearer token¶

1
2

curl http://localhost:8000/api/v1/courses/ \
  -H "Authorization: Bearer ${TEACHER_API_TOKEN}"

Webhook endpoint¶

1
2
3
4

curl -X POST http://localhost:8000/api/v1/webhooks/gitlab \
  -H "X-Gitlab-Token: ${WEBHOOK_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"object_kind":"push"}'

Endpoint inventory (grouped)¶

Current scan: 202 route handlers.

Core API¶

• Courses: /api/v1/courses/*
• Teams: /api/v1/teams/*
• Students: /api/v1/students/*
• Projects: /api/v1/projects/*
• Users: /api/v1/users/*

Event pipeline¶

• Webhook ingest: POST /api/v1/webhooks/gitlab
• DLQ/replay: /api/v1/events/*

Sync and jobs¶

• Sync: /api/v1/teams/{team_id}/sync, /api/v1/courses/{course_id}/sync-all
• Recheck: /api/v1/teams/{team_id}/recheck - immediate metric recomputation (force all checks)
• Job status/SSE: /api/v1/jobs/{job_id}, /api/v1/jobs/{job_id}/stream

Evaluation¶

• Rubrics: /api/v1/courses/{course_id}/rubrics, /api/v1/rubrics/{rubric_id}/*
• Reports: /api/v1/teams/{team_id}/report, /api/v1/reports/{filename}

Extensions¶

• LLM: /api/v1/llm/mr/{project_id}/{mr_iid}
• Docker verify: /api/v1/docker-verify/report
• GitLab parse: /api/v1/gitlab/parse-url

Telemetry¶

• /api/v1/telemetry/* (activity, flags, compliance snapshots, feedback, report preview)

Dashboard routes¶

/dashboard/* includes:

• login/logout/OAuth callback
• dashboards for courses, teams, students, projects
• rubric UI
• admin sections (users, courses, system, events)

Mermaid API domain map¶

flowchart TB
    API["/api/v1"]
    API --> C["Courses"]
    API --> T["Teams"]
    API --> S["Students"]
    API --> P["Projects"]
    API --> U["Users"]
    API --> E["Events/Webhooks"]
    API --> R["Rubrics"]
    API --> SY["Sync + Jobs"]
    API --> TE["Telemetry"]
    API --> X["LLM / Docker Verify / GitLab Parse"]

OpenAPI export¶

1

curl http://localhost:8000/openapi.json > openapi.json

Note: openapi.json, /docs, and /redoc are available in development/debug mode.

Related docs¶

• Architecture
• GitLab webhooks
• Monitoring
• Detailed route inventory: docs/04-api-spec.md