Skip to main content

Guides

Create, edit, delete and list guides and guide steps

GET /guides

Returns a list of all public guides, sorted by guideid.

GET /guides/{guideid}

Returns a comprehensive list of attributes about a guide. Note: Guide Objects have both a 'revisionid' and 'guide_revisionid' field. Only 'guide_revisionid' should be used; 'revisionid' is included for backwards compatibility, but is deprecated and may be removed in the future. The JSON response (not type=xml) includes `release`: the release for the returned revision, in the same shape as `GET /guides/{guideid}/releases`, or null when releases are off or the revision is not released. The JSON response also includes `permissions`, the current user's `canViewCommentsForGuide`, `canSubmitCommentsForGuide`, `canStartWorkOrdersForGuide`, `canAssumeWorkOrdersForGuide`, `canViewDeletedCommentsForGuide`, `canViewGuidePast`, `canViewGuideDraft`, `canTranslateGuide`, `canTranslateGuideIntoLangid` (into the returned guide's language), `canViewJIB`, `canViewSkillsMatrix`, `canGenerateQRCode`, `canExpandAllComments`, `canChangeGuidePrivacy`, `canCreateRelease`, `canCancelRelease`, `canRevertGuide`, `canSetQuizForGuide`, and `canSubmitPeriodicReviewForGuide` for this guide. They describe the current guide, not the requested revision. The JSON response also includes three booleans: `has_draft` is true when the guide has changes newer than its latest (non-cancelled) release, or has no releases; it is always false when releases are off or the current user cannot view the guide's past versions. `ai_generated` is true when the guide is marked as AI generated. `is_draft_only_quiz` is true when the current user can take the guide's quiz and that quiz is not yet on a release (shown as a quiz preview). When `fallbackToSourceText` is set, each step also includes `replaced_langid`: the source langid when the step's untranslated text was filled with the source-language text, or null otherwise.

GET /guides/{guideid}/stats

Returns counts shown on the guide page: `favorites_count` (users who favorited the guide), `completions_count` (users who completed the guide), and `contributors_count` (contributors other than the author). Also returns `contributor_userids`, the userids of up to 50 users who have edited the guide, for @mention suggestions; it is empty unless unique usernames are enabled. Returns 403 when the current user cannot view the guide and 404 when the guide does not exist.

GET /guides/{guideid}/translations/{langid}

Returns the guide's translation state in one language: `source_langid` (the guide's source language), `is_source` (whether `langid` is the source language), `percent_translated` (100 for the source language), `has_unpatrolled` (whether the HEAD revision in `langid` has unpatrolled changes) and `translators` (users credited with the translation and their share of it; empty unless human translation is enabled). Returns 403 when the current user cannot view the guide, 404 when the guide does not exist and 422 when `langid` is not a supported language.

GET /guides/{guideid}/tags

Get all tags on a guide

POST /guides

Create a new guide

PATCH /guides/{guideid}

Updates only the provided fields of an existing guide.

DELETE /guides/{guideid}

Permanently delete a guide

PUT /guides/{guideid}/public

Make a guide public

DELETE /guides/{guideid}/public

Make a guide private

GET /guides/{guideid}/jib

Requires feature-job-instruction-breakdowns and admin privilege. Returns whether JIB is enabled for the guide. Absence of a guide_jib_settings row means enabled.

PUT /guides/{guideid}/jib

Requires feature-job-instruction-breakdowns and admin privilege. Equivalent to the intro sidebar AjaxIO setJibEnabled handler with enabled=true.

DELETE /guides/{guideid}/jib

Requires feature-job-instruction-breakdowns and admin privilege. Equivalent to the intro sidebar AjaxIO setJibEnabled handler with enabled=false.

POST /guides/{guideid}/steps

Add a step to an existing guide.

PATCH /guides/{guideid}/steps/{stepid}

Edit a guide step

DELETE /guides/{guideid}/steps/{stepid}

Remove a guide step

PUT /guides/{guideid}/steporder

Reorder guide steps.

POST /guides/steps/lines/preview

Returns a preview for guide step line. Receives string and returns html.

GET /guides/{guideid}/users

List users allowed to view a private guide. Note: This endpoint is disabled when granular permissions are enabled.

PUT /guides/{guideid}/users/{userid}

Add a user allowed to view a private guide. Note: This endpoint is disabled when granular permissions are enabled.

DELETE /guides/{guideid}/users/{userid}

Remove a user allowed to view a private guide. Note: This endpoint is disabled when granular permissions are enabled.

GET /guides/{guideid}/teams

Get a list of teams that can view this guide. If a guide is private, teams added by authorized users can view the guide. Note: This endpoint is disabled when granular permissions are enabled.

PUT /guides/{guideid}/teams/{teamid}

Add a team that is allowed to view this private guide. Note: This endpoint is disabled when granular permissions are enabled.

DELETE /guides/{guideid}/teams/{teamid}

No longer allow a specified team to view a guide. Note: This endpoint is disabled when granular permissions are enabled.

GET /guides/releases

Show all releases sorted by creation date.

DELETE /guides/releases/{releaseid}

Cancel a pending release. Must be author of release or have admin privileges.

GET /guides/{guideid}/releases

Show all of a guide's releases in descending publish date order. The response body includes both 'release_date' and 'publish_date'. Generally, 'release_date' can be ignored in favor of 'publish_date' which is the date the release actually became available to users. The 'release_date' is used internally when a specific date is picked at the time the release is initialized. Users who cannot view the guide's past versions only see the current release and, when upcoming releases are visible on the site, the upcoming release (the same releases as the guide page's release dropdown). Each release includes `approval_requestid`: the id of the release's approval request, or null when it has none. Returns 403 when the current user cannot view the guide and 404 when the guide does not exist.

GET /guides/{guideid}/revisions

List a guide's revisions in one language, newest first. Each revision includes its date, the userid and username of the user who made it, and `release` ({releaseid, title}), or null when the revision was not released. With `around`, the page containing that revision is returned (`offset` is ignored) along with `previous_guide_revisionid` (the next older revision) and `next_guide_revisionid` (the next newer revision), each null when there is none; these two keys are only present when `around` is set. Requires permission to view the guide's draft. Returns 403 when the current user cannot view the guide's draft, 404 when the guide does not exist, and 422 when `around` is not one of the guide's revisions.

POST /guides/{guideid}/revisions/{guide_revisionid}/revert

Revert a guide to an earlier revision by saving that revision as the guide's new current revision. Returns the new current `guide_revisionid`. Requires permission to edit the guide's draft without patrol. Returns 403 when the current user cannot revert the guide, 404 when the guide or revision does not exist or the revision belongs to another guide, 409 when the revision is already the current revision, and 429 when the current user is rate limited.

POST /guides/releases

Add a new release for a guide.

PATCH /guides/releases/{releaseid}

Modify an existing release for a guide.

POST /guides/duplicateReleases

Duplicates multiples guides at one time at the given release version.

PUT /guides/{guideid}/tag

Adds a tag to a guide, creating the tag if needed.

DELETE /guides/{guideid}/tag

Remove a tag from a guide.

GET /guides/{guideid}/approvalProcesses

Fetch a guide's approval processes.