API ContractsCopy Anchor Link

This document is the human-readable HTTP reference. The route tables in services/api/src/routes/index.ts and services/github-app/src/app.ts, plus the schemas exported by @scs/schemas, remain the executable source of truth.

Service BoundariesCopy Anchor Link

The browser-facing API uses the /api namespace. The GitHub App and Mailer routes are internal and must not be called directly from browser code.

Browser-facing editor responses, proxy updates, mailer requests and responses, and API-to-GitHub-App mutation requests are defined by @scs/schemas. Producers and consumers import those contracts directly so independently deployable workspaces cannot drift behind parallel interfaces or validators.

Common Browser API RulesCopy Anchor Link

• Send session cookies with protected requests.
• Send X-Client-Id: portal where client validation is required.
• Send JSON bodies with Content-Type: application/json.
• Treat cursor and operation identifiers as opaque strings.
• Do not parse human-readable error messages for program logic.
• Validate responses with the matching schema when crossing a trust boundary.

Common status meanings:

Versioned ErrorsCopy Anchor Link

New contracts use ApiErrorEnvelopeSchema from @scs/schemas:

{
  "version": 1,
  "error": {
    "code": "entity_revision_conflict",
    "message": "The project changed after it was loaded.",
    "correlationId": "req_01JAA2V8M7X4G9NK2QF6D3P1ZT",
    "conflict": {
      "resourceType": "project",
      "resourceId": "example-project",
      "expectedRevision": "blob-41",
      "actualRevision": "blob-42"
    }
  }
}

code is stable and machine-readable. message is bounded prose for people. correlationId connects the response to structured logs. Conflict details may contain resource identity and revisions, but never credentials or provider payloads.

PaginationCopy Anchor Link

Page routes accept limit and optional cursor query parameters. The default limit is 25 and the maximum is 100. A cursor is scoped to one route and cannot be reused with another collection.

{
  "version": 1,
  "items": [],
  "page": {
    "nextCursor": null,
    "hasMore": false,
    "total": 0
  }
}

Clients must follow nextCursor rather than constructing cursors or assuming offset pagination. total is optional and must not be required by a generic pagination component.

Durable MutationsCopy Anchor Link

Portal sends Prefer: respond-async for profile, project, course, and offering changes. The request body includes MutationControl:

{
  "idempotencyKey": "01JAA2V8M7X4G9NK2QF6D3P1ZT",
  "expectedRevision": "blob-42"
}

Use missing as the expected revision for a new entity. The same logical user action must reuse its idempotency key when retried. Reusing a key for different input returns a conflict.

A successful submission returns MutationAcceptedSchema with 202 Accepted:

{
  "version": 1,
  "operationId": "op_01JAA2V8M7X4G9NK2QF6D3P1ZT",
  "status": "queued",
  "statusUrl": "/api/operations/op_01JAA2V8M7X4G9NK2QF6D3P1ZT",
  "retryAfterMs": 1000
}

Read or request cancellation of the caller's operation with:

The API owns actor authorization. Emails, provider tokens, and private request bodies are not exposed in operation resources.

Authentication and Current AccountCopy Anchor Link

Better Auth is mounted at /api/auth/* and owns email OTP, Google, GitHub, passkey, account-linking, session, and sign-out endpoints. Email/password auth and parallel custom JWT/WebAuthn routes are not enabled.

Session validation alone is not authorization. Protected requests also check the current permission record so blacklisting and role changes take effect.

Public Profile ManagementCopy Anchor Link

Admin profile suffixes include /schema, /pr, and /student-placement. Unknown suffixes are rejected rather than interpreted as repository paths.

For undergraduate honours profiles, honoursProgramme is required and is the only source used to derive the owning department and special-directory path. Profile mutation requests do not accept an independently selected directory stream.

Projects and AcademicsCopy Anchor Link

The unbounded project collection route is intentionally unavailable. Course and offering arrays remain because Portal editors currently use them as reference data; new collection UIs should use page routes.

Administration and Proxy SettingsCopy Anchor Link

These routes require a non-blacklisted super-admin except /api/me/proxy. Users cannot reset their own attempt counter. Proxy edits use one atomic D1 statement to enforce the attempt limit.

Internal GitHub App APICopy Anchor Link

Every route requires X-Internal-Secret. Operation reads also require X-Actor-Subject-Id; trusted admin reads set X-Actor-Admin: true.

The POST .../operations routes are the durable mutation entry points. The documented PR routes are also active trusted-service contracts. Do not remove either contract without tracing production callers and coordinating the API, Worker, Portal, and deployment rollout.

Mailer APICopy Anchor Link

POST /send requires Authorization: Bearer <MAILER_API_KEY>. Existing callers can provide a raw message:

{
  "to": ["user@pdn.ac.lk"],
  "subject": "Sign in to SCS Portal",
  "html": "<p>Optional HTML body</p>",
  "text": "Optional plain-text body"
}

For supported transactional messages, callers should provide a named template instead of presentation markup. The Portal sign-in request is:

{
  "to": "user@pdn.ac.lk",
  "template": {
    "name": "portal-sign-in-otp",
    "props": {
      "otp": "123456",
      "expiresInMinutes": 5
    }
  }
}

The mailer owns the template subject and renders both HTML and plain text with React Email before SMTP delivery. to contains 1–50 valid addresses. Raw requests require a non-empty subject and at least one of html or text; the OTP template requires a six-digit code and an expiry from 1–60 minutes. Success returns { "ok": true }; validation, authentication, and upstream SMTP failures return 400, 401, and 502.

Changing a ContractCopy Anchor Link

1. Find every producer and consumer, including tests and separate repositories.
2. Change or add the @scs/schemas contract first when it is shared.
3. Prefer additive versioned changes over silently changing existing meaning.
4. Add boundary tests for success, invalid input, authorization, conflict, and retry behavior.
5. Update Portal/API/GitHub App clients together when the contract spans them.
6. Update this document, Schemas, and Operations when applicable.