API Reference

REST API documentation for PBS Knowledge.

Overview

Base URL

Production: https://dartmouthpbs.org/api
Development: http://localhost/api

Authentication

Most endpoints require authentication via JWT:

Authorization: Bearer <token>

Obtain tokens via:

• SAML login flow
• API key (for programmatic access)

Response Format

Responses are JSON:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "statusCode": 400
}

Authentication Endpoints

POST /api/auth/login

Initiate SAML login.

Response: Redirects to IdP

POST /api/auth/callback

SAML callback endpoint.

Body: SAML assertion

Response:

{
  "token": "jwt-token",
  "user": { "id": "...", "email": "..." }
}

GET /api/auth/me

Get current user info.

Response:

{
  "id": "Faculty/abc123",
  "email": "user@dartmouth.edu",
  "role": "faculty",
  "permissions": ["manage_profiles"]
}

People Endpoints

GET /api/people

List people with filtering.

Query Parameters:

• type - Person type (Faculty, UndergraduateStudent, etc.)
• search - Search term
• limit - Results per page (default: 50)
• offset - Pagination offset

Response:

{
  "items": [
    {
      "_id": "Faculty/abc123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@dartmouth.edu"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

GET /api/people/:id

Get a specific person. The :id is Type/identifier (e.g., Faculty/abc123).

Response:

{
  "_id": "Faculty/abc123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@dartmouth.edu",
  "title": "Professor",
  "research_interests": ["cognitive neuroscience"]
}

FERPA note: UndergraduateStudent records are only returned to admins.

POST /api/people

Create a new person (admin only). The person type goes in the body.

Body:

{
  "type": "Faculty",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@dartmouth.edu",
  "education": []
}

Response: 201 with { "id": "Faculty/...", "message": "Person created successfully" }

PUT /api/people/:id

Update a person. Non-admins can only edit their own profile, and identity fields are restricted.

Body: Fields to update

DELETE /api/people/:id

Delete a person (admin only).

Course Endpoints

GET /api/courses

List courses.

Query Parameters:

• department - Filter by department (e.g., "PSYC")
• term - Filter by term (e.g., "24F")
• search - Search by code or title

GET /api/courses/:id

Get course details.

GET /api/courses/:id/sections

Get sections for a course.

GET /api/sections/:id/enrollments

Get enrollments for a section.

Publication Endpoints

GET /api/publications

List publications.

Query Parameters:

• author - Filter by author ID
• year - Filter by year
• search - Search title/abstract

GET /api/publications/:id

Get publication details.

POST /api/publications

Create publication (manual entry).

PUT /api/publications/:id

Update publication.

POST /api/publications/import/:personId

Import publications from OpenAlex for a person.

Degree Endpoints

GET /api/degrees

List degrees.

GET /api/degrees/:id

Get degree with requirements.

Response:

{
  "_id": "Degree/neuro-bs",
  "name": "Neuroscience BS",
  "degree_type": "BS",
  "requirement_groups": [
    {
      "name": "Core Requirements",
      "rules": [...]
    }
  ]
}

POST /api/degrees

Create degree (admin).

PUT /api/degrees/:id

Update degree (admin).

Requirement Endpoints

GET /api/requirement-groups

List requirement groups.

POST /api/requirement-groups

Create requirement group.

GET /api/requirement-rules

List requirement rules.

POST /api/requirement-rules

Create requirement rule.

Student Planning Endpoints

GET /api/student-plans/:studentId

Get student's academic plans.

POST /api/student-plans

Create a new plan.

Body:

{
  "student": "UndergraduateStudent/xyz",
  "plan_name": "Primary Plan",
  "target_degree": "Degree/neuro-bs",
  "planned_courses": [
    {
      "course": "Course/psyc1",
      "term": "25W",
      "status": "planned"
    }
  ]
}

GET /api/student-progress/:studentId

Get requirement progress.

Response:

{
  "overall_progress": 0.65,
  "groups": [
    {
      "name": "Core Requirements",
      "progress": 1.0,
      "satisfied_rules": [...]
    }
  ]
}

Workflows & Approvals

All multi-stage approvals (thesis, independent research, fellowships, award nominations, major plans, graduate milestones) run through the unified workflow system. The model is Workflow → WorkflowInstance → StageInstance → StageApproval; an in-review entity carries the status submitted, and per-approver progress lives on StageApproval records. There is no aggregate /api/approvals/* API — each domain exposes its own queue and decision routes backed by the shared engine:

Domain	Pending queue	Decisions
Honors thesis	GET /api/thesis/pending-approvals	POST /api/thesis/requests/:id/{approve,reject,request-revision}
Independent research	GET /api/independent-research/pending-approvals	per-request decision routes
Fellowships	GET /api/fellowships/pending-approvals	per-application decision routes
Award nominations	GET /api/award-nominations/pending-approvals	per-nomination decision routes
Major plans	/api/major-plan-approvals/...	plan approval routes
Graduate milestones	/api/graduate-milestones/...	mentoring forms, annual reviews, masters thesis, dissertation stages

The engine itself is exposed under /api/workflows (workflow definitions, instances, stage documents). See the Workflows architecture guide for how the system fits together and how to add a new flow.

Admin Endpoints

GET /api/groups

List groups. POST /api/groups, PUT /api/groups/:id, DELETE /api/groups/:id manage them (requires manage_groups).

GET /api/admin/jobs

List background update jobs. GET /api/admin/jobs/:jobId and GET /api/admin/jobs/:jobId/progress report status.

GET /api/queues

Queue statistics for all BullMQ queues. Per-queue job listing, retry, pause/resume under /api/queues/:queueName/....

GET /api/schedulers

List recurring scheduled jobs across queues. POST /api/schedulers/:queueName creates one; publication syncs are managed under /api/schedulers/publication-sync/....

POST /api/dartmouth-sync/courses · /sections · /people

Run Dartmouth API syncs (admin only). Configuration at GET/PUT /api/dartmouth-sync/config; term data at /api/dartmouth-sync/terms.

POST /api/admin/publications/import · /api/admin/citations/update

Trigger publication import / citation refresh jobs for all researchers.

Schema Endpoints

GET /api/schemas

List schemas (?format=summary for a compact list).

GET /api/schemas/:entityType

Get the schema for an entity type.

Response: JSON Schema for the type

Search Endpoints

GET /api/search/all

Search people, courses, and labs together.

Query Parameters:

• q - Search query (min 2 characters)
• limit - Max results

FERPA note: student records are excluded from results for non-admin callers.

GET /api/search/people · /courses · /labs

Search a single entity class. /people accepts a role filter (e.g., Faculty).

Interactive API Docs

The running server hosts Swagger UI at /documentation with the complete, always-current endpoint catalog — use it as the authoritative reference; this page covers the most-used endpoints only.

Error Codes

Code	Meaning
400	Bad Request - Invalid input
401	Unauthorized - Not authenticated
403	Forbidden - Not authorized
404	Not Found - Resource doesn't exist
409	Conflict - Duplicate or version conflict
500	Internal Error - Server error

Rate Limiting

API requests are rate limited:

• Authenticated: 1000 requests/minute
• Unauthenticated: 100 requests/minute

Headers indicate limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200