BlueForge
Docs / API reference

Two surfaces, one origin.

The faculty API and the student API are served from the same admin deployment, under different version prefixes. This page summarizes both. The full machine-readable contract is the OpenAPI 3.1 spec in the repository.

OpenAPI spec

The hand-authored, valid OpenAPI 3.1 document covering every endpoint and schema below lives in the repository at:

OpenAPI 3.1 spec path
docs/api/openapi.yaml

Load it into any OpenAPI viewer or client generator. The summaries below track that file; the file is canonical.

Student API

Base URL https://app.blueforge.dev/api/student/v1. Auth is a per-student key sent as Authorization: Bearer <api-key>. JSON only. Errors carry a stable error.code.

  • GET /shares. List shares you can access.
  • GET /shares/:id. Share metadata: name, tables, columns, active version. No transformation details.
  • GET /shares/:id/schema. Current served per-table schema, reflecting any drift events that have fired.
  • GET /shares/:id/records. Records from one table where arrival_ts > since, ordered ascending. Query: table, since, limit. Returns records, nextCursor, watermark.
  • GET /shares/:id/records/stream. Long-poll. Holds up to 30s, returns as soon as new records satisfy the watermark.
  • POST /sql. One read-only SELECT scoped to your shares. Restricted v1 subset. Non-SELECT is rejected with sql_not_allowed.
  • GET /shares/:id/manifest. The manifest, only if the instructor revealed it. Otherwise 403 manifest_not_released.

The same five reads are exposed as MCP tools at https://mcp.blueforge.dev: list_shares, describe_share, read_records, sql, get_manifest.

Faculty API

Base URL https://app.blueforge.dev/api/v1. Auth is the Supabase Auth session cookie set by the admin app sign-in; this surface is browser and session authenticated, not bearer-token authenticated. Authorization is row-scoped by RLS plus ownership checks in service-role paths.

  • Courses. GET/POST /courses, GET/PATCH/DELETE /courses/:id.
  • Shares. GET/POST /courses/:id/shares, GET/PATCH /shares/:id, GET/POST /shares/:id/versions (POST validates and publishes a full config), GET /shares/:id/manifest, GET /shares/:id/preview?n=10.
  • Seed pools. GET/POST /seed-pools (POST returns a presigned upload URL), GET/DELETE /seed-pools/:id.
  • Roster and keys. GET /courses/:id/students, POST /courses/:id/students/import, POST /courses/:id/students/:sid/api-keys, POST /courses/:id/api-keys/issue-all, DELETE /api-keys/:id. Issued keys are returned exactly once.
  • Usage. GET /courses/:id/usage/summary, GET /courses/:id/usage/students.

Errors

Every error is a JSON body of the shape { "error": { "code", "message", "details?" } }. The code values are stable: unauthorized, forbidden, not_found, validation_failed, invalid_api_key, rate_limited, manifest_not_released, sql_not_allowed, internal_error. Raw database messages are never returned.

New to the platform? Start with the student quick start or the faculty quick start.