API Reference

One API. Every Cognaxa capability.

The Cognaxa REST API exposes every primitive — courses, quizzes, proctoring events, analytics, webhooks, and SSO — behind a single tenant-scoped bearer token. No separate endpoints to integrate the proctoring vendor or the analytics vendor, because there are none.

Authentication

All API requests are authenticated with a bearer token scoped to a single tenant. Tokens are issued from the tenant admin panel and respect RBAC.

curl https://api.cognaxa.genfinish.com/v1/courses \
  -H "Authorization: Bearer ck_live_${TOKEN}" \
  -H "X-Tenant-Id: ${TENANT_ID}"

Courses

Create, read, update, and publish courses. Supports modules, lessons, and ordered content.

GET    /v1/courses
POST   /v1/courses
GET    /v1/courses/:id
PATCH  /v1/courses/:id
DELETE /v1/courses/:id
POST   /v1/courses/:id/publish

Quizzes & Attempts

Build quizzes, manage questions, and retrieve attempts. Server-synced timers prevent client-side clock tampering.

GET    /v1/quizzes/:id
POST   /v1/quizzes/:id/attempts
PATCH  /v1/quizzes/:id/attempts/:attemptId
GET    /v1/quizzes/:id/attempts/:attemptId/score

Proctoring Events

Fetch proctoring incidents for a session. Each event is tenant-scoped. Outbound webhook delivery is on the roadmap — see the Webhooks section below.

GET  /v1/proctoring/sessions/:id
GET  /v1/proctoring/sessions/:id/events

Users & RBAC

Provision users, assign roles (student / teacher / admin), and integrate with SSO (SAML 2.0, OIDC).

GET    /v1/users
POST   /v1/users
PATCH  /v1/users/:id/role
POST   /v1/sso/saml/callback
POST   /v1/sso/oidc/callback

Analytics Export

Pull course, quiz, and learner analytics in bulk for your data warehouse. JSON and NDJSON supported.

GET  /v1/analytics/courses?from=2026-01-01&to=2026-03-31
GET  /v1/analytics/attempts.ndjson
GET  /v1/analytics/learners

Webhooks (Planned)

Outbound webhooks are on the Enterprise roadmap. The planned shape: subscribe to events, verify deliveries with HMAC-SHA256 using your webhook secret, with exponential-backoff retries. Timing and the final event list will be confirmed on the GA announcement.

Planned events:
  course.published
  quiz.attempt.submitted
  quiz.attempt.graded
  proctoring.incident.flagged
  certificate.issued
  user.provisioned

Rate Limits

Per-tenant token bucket. Default: 600 requests/minute, 10,000 requests/hour. Enterprise plans are configurable. 429 responses include `Retry-After`.

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 587
X-RateLimit-Reset:     1712078400
Retry-After:           12

Errors

Conventional HTTP status codes. Error bodies include a stable `code` for programmatic handling and a `request_id` for support tickets.

{
  "code": "quiz.attempt.timer_expired",
  "message": "Server-enforced timer elapsed.",
  "request_id": "req_01HX..."
}

Need access to the full spec?

The complete OpenAPI 3.1 document, sandbox credentials, and the integration guide are available to Enterprise customers and verified prospects.

Request API Access → See Integrations →