REST API v1

API Reference

Private beta, not yet generally available. The REST API v1 ships on enterprise plans and is gated; endpoints below return 404 Not available until access is enabled for your organization. This page documents the planned interface. Email us to request access.

Automate course creation, enrollment, and learner management programmatically. All responses are JSON. Every request must include a valid API key.

Base URL: https://swiftscorm.comResponse header: X-SwiftSCORM-API-Version: 1 (returned on responses; not required on requests)

Authentication

Pass your API key in the Authorization header on every request. Keys start with sk_live_. Create and manage keys from your SwiftSCORM dashboard.

fetch

const res = await fetch(
  "https://swiftscorm.com/api/v1/courses",
  {
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY"
    }
  }
);

curl

curl https://swiftscorm.com/api/v1/courses \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Security: API keys carry full org access within their granted scopes. Store them in environment variables, never in client-side code or version control. Keys are shown only at creation time; they cannot be retrieved later.

API Key Management (enterprise beta, gated)

API keys are managed via your dashboard, not via the v1 API itself (keys require a dashboard token, not another API key).

GET/api/keys?orgId=xxxAuth: Dashboard token

List all keys for an org. Never returns the raw key, only prefix, name, scopes, and metadata.

POST/api/keysAuth: Dashboard token

Create a new key. Returns the raw sk_live_xxx key once, it cannot be retrieved again. Body: { orgId, name, scopes[], expiresAt? }

DELETE/api/keys?id=xxxAuth: Dashboard token

Permanently revoke a key. Returns 204.

Scopes

Each API key is granted a set of scopes at creation time. Requests using a key without the required scope return 403 Forbidden.

Scope	Description
read:courses	List and retrieve courses.
write:courses	Create and update courses.
delete:courses	Delete courses.
read:enrollments	List and retrieve enrollments.
write:enrollments	Create and update enrollments.
read:users	List and retrieve org users.
write:users	Create org users.

Rate Limits

~100

Requests per minute

per IP, per server instance

60 s

Window

fixed window

429

Response on limit

Too Many Requests

If you need higher limits for batch automation, contact hello@swiftscorm.com.

Error Responses

All errors return JSON with an error string and the HTTP status code.

{ "error": "Forbidden. This key does not have the 'write:courses' scope.", "status": 403 }

Status	Meaning
`400`	Bad Request: missing or invalid parameter.
`401`	Unauthorized: missing, invalid, expired, or revoked API key.
`403`	Forbidden: key does not have the required scope, or resource belongs to a different org.
`404`	Not Found: resource does not exist.
`409`	Conflict: a resource with this identifier already exists (e.g., duplicate user email).
`429`	Too Many Requests: rate limit exceeded. Back off and retry.
`500`	Internal Server Error: something went wrong on our end.
`501`	Not Implemented: operation not supported in this deployment (e.g., in-memory dev mode).

Courses

GET/api/v1/coursesread:courses

List all courses for your org. Supports pagination, kind, and tag filtering.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Max results per page (max 100).
`offset`	integer	0	Pagination offset.
`kind`	string	—	Filter by type: quiz or lesson.
`tag`	string	—	Filter to courses with this tag.

Response

{
  "data": [
    {
      "id": "c1d2e3f4-...",
      "title": "Fire Safety Fundamentals",
      "kind": "quiz",
      "passScore": 80,
      "language": "English",
      "tags": ["safety", "compliance"],
      "createdAt": "2025-01-15T09:00:00.000Z",
      "enrollmentCount": 42
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

POST/api/v1/courseswrite:courses

Create a minimal course shell. Returns a dashboardUrl to add quiz content via the SwiftSCORM app.

Request Body

{
  "title": "Fire Safety Fundamentals",
  "kind": "quiz",
  "passScore": 80,
  "language": "English",
  "tags": ["safety", "compliance"]
}

Response

{
  "data": { "id": "c1d2e3f4-...", "title": "Fire Safety Fundamentals", ... },
  "dashboardUrl": "https://swiftscorm.com/dashboard"
}

GET/api/v1/courses/:idread:courses

Fetch a single course by ID.

Response

{
  "data": {
    "id": "c1d2e3f4-...",
    "title": "Fire Safety Fundamentals",
    "kind": "quiz",
    "passScore": 80,
    "language": "English",
    "tags": ["safety"],
    "createdAt": "2025-01-15T09:00:00.000Z",
    "enrollmentCount": 42
  }
}

PATCH/api/v1/courses/:idwrite:courses

Update course metadata. Send only the fields you want to change.

Request Body

{
  "title": "Updated Title",
  "passScore": 75,
  "tags": ["compliance"]
}

Response

{ "data": { "id": "...", "title": "Updated Title", "passScore": 75, ... } }

DELETE/api/v1/courses/:iddelete:courses

Delete a course. Returns 204 No Content on success.

Response

204 No Content

Enrollments

GET/api/v1/enrollmentsread:enrollments

List enrollments across all org courses. Filter by course or status.

Query Parameters

Parameter	Type	Default	Description
`courseId`	string	—	Filter to a specific course.
`status`	string	—	Filter: invited, in_progress, passed, or failed.
`limit`	integer	20	Max results per page (max 100).
`offset`	integer	0	Pagination offset.

Response

{
  "data": [
    {
      "id": "e1f2g3h4-...",
      "courseId": "c1d2e3f4-...",
      "learnerEmail": "alice@acme.com",
      "learnerName": "Alice Smith",
      "status": "passed",
      "score": 92,
      "attempts": 1,
      "completedAt": "2025-02-10T14:30:00.000Z",
      "createdAt": "2025-01-20T08:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

POST/api/v1/enrollmentswrite:enrollments

Enroll a learner in a course. Returns the enrollment and a one-time invite URL to send to the learner.

Request Body

{
  "courseId": "c1d2e3f4-...",
  "learnerEmail": "alice@acme.com",
  "learnerName": "Alice Smith"
}

Response

{
  "data": {
    "id": "e1f2g3h4-...",
    "courseId": "c1d2e3f4-...",
    "learnerEmail": "alice@acme.com",
    "status": "invited",
    "score": null,
    "attempts": 0,
    "completedAt": null,
    "createdAt": "2025-06-01T10:00:00.000Z"
  },
  "inviteUrl": "https://swiftscorm.com/learn/abc123..."
}

GET/api/v1/enrollments/:idread:enrollments

Fetch a single enrollment by ID.

Response

{ "data": { "id": "...", "status": "passed", "score": 88, ... } }

PATCH/api/v1/enrollments/:idwrite:enrollments

Update enrollment status and/or score. Best-score logic is applied automatically.

Request Body

{ "status": "passed", "score": 88 }

Response

{ "data": { "id": "...", "status": "passed", "score": 88, "completedAt": "..." } }

Users

GET/api/v1/usersread:users

List org users. Never returns passwords or SSO credentials.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Max results per page (max 100).
`offset`	integer	0	Pagination offset.
`department`	string	—	Filter by department name.
`role`	string	—	Filter by role: admin, manager, or learner.

Response

{
  "data": [
    {
      "id": "u1v2w3x4-...",
      "email": "alice@acme.com",
      "name": "Alice Smith",
      "role": "learner",
      "department": "Engineering",
      "jobTitle": "Software Engineer",
      "avatarUrl": null,
      "lastLoginAt": "2025-05-31T09:00:00.000Z",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

POST/api/v1/userswrite:users

Create a new user in your org.

Request Body

{
  "email": "alice@acme.com",
  "name": "Alice Smith",
  "role": "learner",
  "department": "Engineering",
  "jobTitle": "Software Engineer"
}

Response

{ "data": { "id": "u1v2w3x4-...", "email": "alice@acme.com", "role": "learner", ... } }

Questions or feedback? Email hello@swiftscorm.com to request access and manage your API keys.