Build against the Personal Academy API

Quickstart

Every request carries an API key. Base path is /api/v1. Responses are { data, meta? } on success and { error, code, ... } on failure.

curl -sS https://<your-host>/api/v1/learn/courses?page_size=2 \
  -H"Authorization: Bearer $ACADEMY_API_KEY"

# Machine-readable descriptions, no key required:
curl -sS https://<your-host>/api/v1/openapi.json           # OpenAPI 3.1
curl -sS https://<your-host>/api/v1/versions               # version lifecycle
curl -sS https://<your-host>/api/v1/limits                 # published rate limits
curl -sS https://<your-host>/api/v1/graphql/schema.graphql # GraphQL SDL

A rendered browser for the OpenAPI document lives at /api/v1/docs, with a per-module view at /api/v1/docs?module=learn.

Authentication

Send Authorization: Bearer <key>. There is no cookie or session path for a machine caller. The key is hashed with SHA-256 before it is looked up; the raw value is never stored and never logged, which also means it cannot be shown to you again after it is created.

What a key can do is the intersection of three things, all checked live on every request:

1. The key’s module scopes. A key scoped for module.learn cannot read assessment endpoints, whatever else it holds.
2. Your organisation’s entitlements. Checked independently of the key. If a module leaves your plan, calls to it stop on the next request — not when the key is next reissued.
3. The live permissions of the principal the key acts as. Recomputed from that person’s current roles every time, then intersected with the permissions the key was explicitly granted. A key can never do more than its owner currently can, and never inherits everything its creator could do.

Routes that act as one learner (the /api/v1/me/* group) also need the X-Learner-Id header, set to that learner’s external_id or user_id. The learner must belong to the key’s organisation, and the header never acts as anyone holding administrator permissions.

Versioning and the deprecation policy

The version is the path segment: /api/v1. Its lifecycle is not a promise on this page — it is a row the API reads on every request, published at GET /api/v1/versions.

What each status does to your requests

• current — served normally. Every response carries X-API-Version.
• deprecated — still served, but every response adds RFC 8594’s Deprecation and Sunset headers (both HTTP-dates) and Link: <…>; rel="deprecation". You find out on calls you are already making; you do not have to be subscribed to anything.
• sunset — every request answers 410 Gone with a body naming replacement_version, sunset_on and where the migration is documented. Not a 404, because the URL is not unknown; it is retired.

What we may change inside a version

Rate limits

60 requests per 60 seconds, per API key on every plan, counted in fixed windows. Counted per API key, in fixed 60-second windows. Requests refused before the limiter runs (unauthenticated, out-of-scope, unentitled or lacking the permission) do not consume the quota.

Two things move that ceiling, and only in one direction each. The limit.api_rpm entitlement raises it when your plan includes a higher one. The api.requests_per_minute setting lets your own administrator lower it — useful to protect a downstream system — but it can never raise it above what the plan includes. Call GET /api/v1/limits with your key to see the resolved figure for your organisation.

Policies by key type

Organisation keys and partner-level keys are counted under separate policies. A partner-level key acts for the partner, so its home organisation’s plan and setting do not apply to it. A policy marked pending shows the limit enforced today; its published limit has not been decided yet.

Headers on every response

The RateLimit-* headers are omitted — rather than filled with a guess — in the rare case where the limiter itself cannot be consulted. If that happens, requests are allowed through: a quota outage should not become a total outage. Authentication, scope, entitlement and permission checks do the opposite and fail closed.

Requests refused before the limiter runs (no key, wrong scope, module not entitled, permission missing) do not consume quota.

Webhook delivery

These are the values the delivery worker runs with, also published at GET /api/v1/limits under webhook_delivery.

Endpoints

Generated from the running route table. The scope and permission columns are the exact values checked on each request.

Full field lists, filters and sort whitelists are in the OpenAPI document: /api/v1/openapi.json (OpenAPI 3.1, JSON Schema 2020-12), or per module at /api/v1/<module>/openapi.json.

Pagination

List endpoints are cursor-paginated, not offset-paginated: under concurrent writes an offset page can skip or repeat a row, and paging deep into a large table gets slower the further you go. Neither happens here.

GET /api/v1/learn/courses?page_size=50&sort=-created_at
{"data": [ ... ],"meta": {"cursor": {"next":"eyJ2IjoiMjAyNi0wOS0xMFQxMDoyMjozM1oiLCJpZCI6Ii4uLiJ9" } }
}

# next page: pass meta.cursor.next back
GET /api/v1/learn/courses?page_size=50&sort=-created_at&cursor=eyJ2Ijoi...

• page_size defaults to 25 and is capped at 100. A larger value is silently reduced to the cap rather than refused.
• meta.cursor.next is null on the last page. Treat the cursor as opaque; its encoding is not part of the contract.
• sort=field or sort=-field for descending, from each endpoint’s whitelist. An unrecognised value falls back to the default ordering instead of erroring — which rows you get never depends on it.

GraphQL

One endpoint, POST /api/v1/graphql, over exactly the same read models as REST, with the same scope and permission checks applied to each root field independently. A key scoped for one module and not another gets the half it is entitled to plus a machine-readable refusal for the half it is not — not an all-or-nothing 403.

curl -sS https://<your-host>/api/v1/graphql \
  -H"Authorization: Bearer $ACADEMY_API_KEY" \
  -H"Content-Type: application/json" \
  -d '{"query":"{ learnCourses(first: 5, status: \"published\") { nodes { id title created_at } pageInfo { endCursor hasNextPage } } }"}'

What it deliberately does not do

• No mutations or subscriptions. This API is read-only. Writes go through REST endpoints where each one can be audited on its own.
• Introspection is refused (__schema, __type). An introspection query makes the server enumerate its own type graph on demand and tells you nothing the published schema does not. The full SDL is below and at /api/v1/graphql/schema.graphql. __typename still works.
• No fragments, variables or directives. The schema is 17 flat row types deep; each of these is refused with an error naming it, rather than half-supported.

Query bounds

An unbounded GraphQL endpoint is a denial-of-service surface handed to the caller, so queries are bounded by cost and refused before any database query runs. The formula is published so you can compute it yourself rather than discovering the ceiling by hitting it.

Schema

Generated from the same route definitions as the REST endpoints, so a field here cannot describe a shape REST does not return. Field names are the column names (created_at, not createdAt) so the two documents read identically.

# Personal Academy GraphQL API — read-only, version 1.
#
# One POST endpoint: /api/v1/graphql
# Auth: the same Authorization: Bearer <api key> as REST, resolved by the same code,
#       with the same per-module scope and per-principal permission checks applied to
#       each root field independently. There is no second authorisation path.
# Limits: queries are bounded by depth and by complexity; see the errors below and the
#         published limits at /api/v1/limits. One GraphQL request consumes one unit of
#         the same per-key rate limit REST uses.
# Introspection (__schema, __type) is refused. This document is the schema.
# Mutations and subscriptions do not exist: this API is read-only by design, and writes
#         go through the REST endpoints where each one can be audited on its own.

scalar JSON

type PageInfo {
  "Opaque cursor for the next page, or null on the last page. Pass back as the after argument."
  endCursor: String
  hasNextPage: Boolean!
}

"""List quiz attempts. Quiz attempts across the caller's tenant, from the append-only attempts ledger. Never returns a quiz block's correct answer — this table doesn't carry one."""
type AssessAttemptsItem {
  id: ID!
  user_id: ID!
  lesson_id: ID!
  block_id: ID!
  attempt_no: Int!
  selected_answer: String!
  is_correct: Boolean!
  answered_at: String!
}

type AssessAttemptsConnection {
  nodes: [AssessAttemptsItem!]!
  pageInfo: PageInfo!
}

"""List issued certificates. Certificates issued across the caller's tenant. Deliberately omits verification_code — see this route's file header."""
type AssessCertificatesItem {
  id: ID!
  user_id: ID!
  course_id: ID!
  template_id: ID
  learner_name: String!
  issued_at: String!
}

type AssessCertificatesConnection {
  nodes: [AssessCertificatesItem!]!
  pageInfo: PageInfo!
}

"""List training completion records. OSHA-style training records: one immutable, snapshotted row per course completion, for the tenant."""
type AssessCompletion-recordsItem {
  id: ID!
  user_id: ID!
  course_id: ID
  course_title: String!
  course_version: Int!
  content_summary: JSON!
  attendee_name: String!
  attendee_job_title: String
  trainer_id: ID
  trainer_name: String
  trainer_qualifications: String
  score: Int
  completed_at: String!
}

type AssessCompletion-recordsConnection {
  nodes: [AssessCompletion-recordsItem!]!
  pageInfo: PageInfo!
}

"""List session registrations. Registrations (confirmed, waitlisted or cancelled) for the caller's tenant."""
type EventsRegistrationsItem {
  id: ID!
  session_id: ID!
  user_id: ID!
  status: String!
  waitlist_position: Int
  registered_at: String!
  cancelled_at: String
}

type EventsRegistrationsConnection {
  nodes: [EventsRegistrationsItem!]!
  pageInfo: PageInfo!
}

"""List sessions. Classroom and virtual sessions for the caller's tenant."""
type EventsSessionsItem {
  id: ID!
  course_id: ID
  title: String!
  description: String!
  delivery_mode: String!
  location: String
  virtual_provider: String
  trainer_id: ID
  starts_at: String!
  ends_at: String!
  session_timezone: String!
  capacity: Int!
  status: String!
  created_at: String!
}

type EventsSessionsConnection {
  nodes: [EventsSessionsItem!]!
  pageInfo: PageInfo!
}

"""List completion records. Immutable, snapshotted course-completion records for the tenant, for reporting/insights-scoped keys."""
type InsightsCompletionsItem {
  id: ID!
  user_id: ID!
  course_id: ID
  course_title: String!
  score: Int
  completed_at: String!
  expires_at: String
  recert_status: String!
}

type InsightsCompletionsConnection {
  nodes: [InsightsCompletionsItem!]!
  pageInfo: PageInfo!
}

"""List courses. Courses visible to the caller's tenant, newest-created first by default."""
type LearnCoursesItem {
  id: ID!
  title: String!
  description: String
  status: String!
  difficulty_level: String
  duration_minutes: Int
  estimated_minutes: Int
  created_at: String!
  updated_at: String!
}

type LearnCoursesConnection {
  nodes: [LearnCoursesItem!]!
  pageInfo: PageInfo!
}

"""Get one course. A single course by id, scoped to the caller's tenant."""
type LearnCoursesIdItem {
  id: ID!
  title: String!
  description: String
  status: String!
  difficulty_level: String
  duration_minutes: Int
  estimated_minutes: Int
  created_at: String!
  updated_at: String!
}

"""List enrolments. Enrolments across the caller's tenant. Permission: learner.progress.tenant (the existing permission key that already gates cross-learner progress reads elsewhere; this route does not invent a narrower one)."""
type LearnEnrolmentsItem {
  id: ID!
  user_id: ID!
  course_id: ID!
  enrolled_at: String!
  completed_at: String
  last_lesson_id: ID
}

type LearnEnrolmentsConnection {
  nodes: [LearnEnrolmentsItem!]!
  pageInfo: PageInfo!
}

"""List departments. Departments (and other org-unit types) for the caller's tenant, including the parent_id tree structure."""
type OrgDepartmentsItem {
  id: ID!
  name: String!
  slug: String!
  description: String
  parent_id: ID
  type: String!
  color: String!
  created_at: String!
}

type OrgDepartmentsConnection {
  nodes: [OrgDepartmentsItem!]!
  pageInfo: PageInfo!
}

"""List groups. Groups (static and dynamic) for the caller's tenant."""
type OrgGroupsItem {
  id: ID!
  name: String!
  description: String!
  is_dynamic: Boolean!
  owner_department_id: ID
  created_at: String!
}

type OrgGroupsConnection {
  nodes: [OrgGroupsItem!]!
  pageInfo: PageInfo!
}

"""List organisation members. Member directory for the caller's tenant: profile fields and department/manager links. No auth identity or email is included."""
type OrgUsersItem {
  user_id: ID!
  full_name: String!
  title: String!
  department_id: ID
  job_title_id: ID
  manager_id: ID
  timezone: String
  created_at: String!
  updated_at: String!
}

type OrgUsersConnection {
  nodes: [OrgUsersItem!]!
  pageInfo: PageInfo!
}

"""List learning-path enrolments. Who is enrolled in which learning path, for the caller's tenant."""
type PathsEnrolmentsItem {
  id: ID!
  user_id: ID!
  path_id: ID!
  enrolled_at: String!
  completed_at: String
  due_at: String
  assignment_source: String!
}

type PathsEnrolmentsConnection {
  nodes: [PathsEnrolmentsItem!]!
  pageInfo: PageInfo!
}

"""List learning paths. Learning paths (ordered course sequences) for the caller's tenant."""
type PathsPathsItem {
  id: ID!
  title: String!
  description: String
  slug: String
  is_public: Boolean!
  thumbnail_url: String
  created_at: String!
  updated_at: String!
}

type PathsPathsConnection {
  nodes: [PathsPathsItem!]!
  pageInfo: PageInfo!
}

"""List competencies. The competency framework for the caller's tenant (max_level and category per competency)."""
type SkillsCompetenciesItem {
  id: ID!
  name: String!
  description: String!
  category: String!
  max_level: Int!
  created_at: String!
  updated_at: String!
}

type SkillsCompetenciesConnection {
  nodes: [SkillsCompetenciesItem!]!
  pageInfo: PageInfo!
}

"""List learner skill scores. Per-learner, per-skill scores for the caller's tenant."""
type SkillsScoresItem {
  id: ID!
  user_id: ID!
  skill_id: ID!
  score: Int!
  updated_at: String!
}

type SkillsScoresConnection {
  nodes: [SkillsScoresItem!]!
  pageInfo: PageInfo!
}

"""List skills. The skill catalogue for the caller's tenant."""
type SkillsSkillsItem {
  id: ID!
  name: String!
  description: String
  parent_skill_id: ID
  external_source: String
  external_id: String
  created_at: String!
}

type SkillsSkillsConnection {
  nodes: [SkillsSkillsItem!]!
  pageInfo: PageInfo!
}

type Query {
  "List quiz attempts. Requires scope module.assessment and permission learner.progress.tenant."
  assessAttempts(first: Int, after: String, sort: String, lesson_id: String, user_id: String, correct: Boolean): AssessAttemptsConnection
  "List issued certificates. Requires scope module.assessment and permission learner.progress.tenant."
  assessCertificates(first: Int, after: String, sort: String, course_id: String, user_id: String): AssessCertificatesConnection
  "List training completion records. Requires scope module.assessment and permission learner.progress.tenant."
  assessCompletionRecords(first: Int, after: String, sort: String, course_id: String, user_id: String): AssessCompletion-recordsConnection
  "List session registrations. Requires scope module.events and permission course.edit.any."
  eventsRegistrations(first: Int, after: String, sort: String, session_id: String, user_id: String, status: String): EventsRegistrationsConnection
  "List sessions. Requires scope module.events and permission course.view."
  eventsSessions(first: Int, after: String, sort: String, status: String, course_id: String, search: String): EventsSessionsConnection
  "List completion records. Requires scope module.insights and permission report.view.tenant."
  insightsCompletions(first: Int, after: String, sort: String, course_id: String, user_id: String): InsightsCompletionsConnection
  "List courses. Requires scope module.learn and permission course.view."
  learnCourses(first: Int, after: String, sort: String, status: String, search: String): LearnCoursesConnection
  "Get one course. Requires scope module.learn and permission course.view."
  learnCourse(id: ID!): LearnCoursesIdItem
  "List enrolments. Requires scope module.learn and permission learner.progress.tenant."
  learnEnrolments(first: Int, after: String, sort: String, course_id: String, completed: Boolean): LearnEnrolmentsConnection
  "List departments. Requires scope module.org and permission report.view.tenant."
  orgDepartments(first: Int, after: String, sort: String, search: String, type: String): OrgDepartmentsConnection
  "List groups. Requires scope module.org and permission report.view.tenant."
  orgGroups(first: Int, after: String, sort: String, search: String, is_dynamic: Boolean): OrgGroupsConnection
  "List organisation members. Requires scope module.org and permission report.view.tenant."
  orgUsers(first: Int, after: String, sort: String, department_id: String, search: String): OrgUsersConnection
  "List learning-path enrolments. Requires scope module.paths and permission report.view.tenant."
  pathsEnrolments(first: Int, after: String, sort: String, path_id: String, user_id: String, completed: String): PathsEnrolmentsConnection
  "List learning paths. Requires scope module.paths and permission report.view.tenant."
  pathsPaths(first: Int, after: String, sort: String, search: String, is_public: String): PathsPathsConnection
  "List competencies. Requires scope module.skills and permission report.view.tenant."
  skillsCompetencies(first: Int, after: String, sort: String, category: String, search: String): SkillsCompetenciesConnection
  "List learner skill scores. Requires scope module.skills and permission report.view.tenant."
  skillsScores(first: Int, after: String, sort: String, user_id: String, skill_id: String): SkillsScoresConnection
  "List skills. Requires scope module.skills and permission report.view.tenant."
  skillsCatalogue(first: Int, after: String, sort: String, search: String): SkillsSkillsConnection
}

schema {
  query: Query
}

Error catalogue

Every non-2xx response is {"error":"...","code":"..." }, sometimes with extra fields. code is what you branch on; error is for a human reading a log. Over GraphQL the same codes arrive in errors[].extensions.code.

A 404 on a single-resource read means “no such id in your organisation”. A record that exists but belongs to someone else is reported the same way, on purpose: a 403 would confirm the id exists.