Skip to main content

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/:type/:id​

Get a specific person.

Response:

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

POST /api/people/:type​

Create a new person.

Body:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@dartmouth.edu"
}

Response: Created person object

PUT /api/people/:type/:id​

Update a person.

Body: Fields to update

Response: Updated person object

DELETE /api/people/:type/: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": [...]
    }
  ]
}

Milestone Endpoints​

GET /api/milestones/templates​

List milestone templates.

GET /api/milestones/instances/:personId​

Get milestone instances for a person.

POST /api/milestones/instances/:id/submit​

Submit a milestone.

POST /api/milestones/instances/:id/approve​

Approve a milestone (approver only).

Admin Endpoints​

GET /api/admin/groups​

List permission groups.

POST /api/admin/groups​

Create a group.

PUT /api/admin/groups/:id/members​

Update group members.

GET /api/admin/jobs​

List background jobs.

POST /api/admin/jobs/:queue/run​

Trigger a job manually.

GET /api/admin/sync/status​

Get sync status.

POST /api/admin/sync/:type/run​

Run a sync job.

Schema Endpoints​

GET /api/schema​

Get full schema.

GET /api/schema/:type​

Get schema for entity type.

Response: JSON Schema for the type

Search Endpoints​

GET /api/search​

Global search across entities.

Query Parameters:

  • q - Search query
  • types - Entity types to search (comma-separated)
  • limit - Max results

Error Codes​

CodeMeaning
400Bad Request - Invalid input
401Unauthorized - Not authenticated
403Forbidden - Not authorized
404Not Found - Resource doesn't exist
409Conflict - Duplicate or version conflict
500Internal 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