Skip to main content

Articles in this section

Guides v2

  • Last updated:

Note: The v2 API is currently in beta. Functionality may change, though we will do our best to not break existing beta APIs. The feature is also currently behind a feature flag, please contact your Account Manager for access.

The v2 Guide API is a read-only, reporting-and-integration API. It gives you a clean, consistent way to pull WorkRamp learning content and learner-progress data into your own systems — data warehouses, dashboards, intranets, audit tools. A "Guide" is a piece of learning content; a "step" is one item inside a guide (video, file, quiz question, text); a "guide assignment" is the record of one learner being given a guide.

All seven v2 endpoints are GET requests (nothing is created, changed, or deleted through them) and live under https://app.workramp.com/api/v2. They are documented in WorkRamp's OpenAPI specification, grouped under four tags: Guides, Guide Steps, Guide Assignments, and Guide Assignment Steps.

The v2 endpoints and their use cases

Content (the guide itself)

  1. List guides — GET /guides. A paginated inventory of every guide in your account. Optional includes can add tags, skills, and where each guide appears. Use it to sync your whole catalogue into a search index or warehouse.

  2. Get a guide — GET /guides/{id}. Full detail on one guide (title, description, publish state, estimated duration, author, tags/skills, badge, sharing settings). Use it to build a formatted "course info" page for a known guide.

  3. List guide steps — GET /guides/{guide_id}/steps. Every content item inside a guide, in order, with its type and section. Use it to report on what a guide contains without anyone clicking through it.

  4. Download a guide step file — GET /guides/{guide_id}/steps/{id}/files/{file_id} For a file-type step (PDF, image, video, audio), returns the downloadable file. Use it to archive a compliance guide's attachments into your own store.

Assignments (a learner's copy and their progress)

  1. List guide assignments - GET /guide_assignments. A paginated list of guide-to-learner assignments, filterable to one learner, each showing status, score, completion %, due date, time spent, and who assigned it. Use it to feed a company-wide "who's assigned what and how far along" dashboard.

  2. Get a guide assignment - GET /guide_assignments/{id}. Full detail on one specific learner-and-guide pairing. Use it to power a drill-in view for a single employee's assignment.

  3. List guide assignment steps - GET /guide_assignments/{guide_assignment_id}/steps

    One learner's step-by-step results for an assignment — each step, whether they got it right, and when they completed it. Use it to build an answer sheet or audit view for grading reviews or compliance evidence.

A quick way to remember it: endpoints 1–4 describe the guide (the template and its content); endpoints 5–7 describe a learner's copy of a guide and their progress through it.

Where to find them

Public developer docs: WorkRamp publishes its API reference at https://developers.workramp.com/v2.0/reference/getting-started

To get started on generating a key for the v2 endpoints you will first need to create a key. Furter details here: API Key Management

How v2 differs from the v1 Guide suite

The v1 Guide endpoints still exist, they covered a smaller area, but are read-and-write. The main differences:

Coverage

v1 only offered: list guides, list a guide's assignments (filterable by user), create an assignment, update an assignment, and delete an assignment. There were also separate log-listing endpoints for guides and guide assignments.

v1 had no single-guide detail endpoint, no way to list the steps inside a guide, no step-file download, and no per-learner step-level results. v2 adds all four.

Read vs. write

v1 mixed reading and writing — you could create, update, and delete assignments through it (mark one complete, change its due date, override a score).

The v2 Guide suite is read-only. The v2 endpoints do not create or modify anything at the moment; assignment write operations remain on the v1 endpoints.

Consistency and design

v1 responses used ad-hoc shapes and had a "legacy mode" that changed whether results were paginated at all.

v2 follows a documented standard throughout: a uniform envelope (all data under a data key, with a sibling pagination object), both offset- and cursor-based pagination (limit 1–200), optional includes for related data, ISO 8601 timestamps, consistent field naming, and a standard error format with error codes.

In this article