Skip to content
shuffl
Get started

Searches the public product guides only. Nothing from a workspace is read, and questions are not saved.

Reference

Knowledge API

36 operations. Generated from the OpenAPI document, so this page always matches the API.

OpenAPI documentErrors and rate limitsSDK and CLI recipes

On this page

knowledge.context

Read nearby passages from the same currently approved version

POST/api/v1/knowledge/context

const result = await shuffl.knowledge.context({
  "passageId": "<passageId>",
  "sourceId": "<sourceId>",
  "versionId": "<versionId>"
});
Request fields (3)
  • passageId string requiredMatches ^passage-[1-9]\d{0,2}$
  • sourceId string (uuid) required
  • versionId string (uuid) required
Response object[]
  • href string required
  • kind "knowledge" | "manager" | "directory" | "playbook" optional
  • passageId string required
  • quote string required
  • sourceId string required
  • title string required
  • versionId string required

knowledge.search

Search currently approved knowledge and return immutable passage citations

POST/api/v1/knowledge/search

const result = await shuffl.knowledge.search({
  "query": "<query>"
});
Request fields (1)
  • query string required2 to 500 characters
Response object[]
  • href string required
  • kind "knowledge" | "manager" | "directory" | "playbook" optional
  • passageId string required
  • quote string required
  • sourceId string required
  • title string required
  • versionId string required

knowledge.acknowledgements.mine

List the Knowledge pages you are asked to read and confirm

POST/api/v1/manage/knowledge/acknowledgements/mine

const result = await shuffl.knowledge.acknowledgements.mine();
Request fields (none)

This operation takes no input.

Response object
  • pages object[] required
    • requestedAt string (date-time) required
    • sourceId string required
    • title string required
    • versionId string required

knowledge.acknowledgements.status

See who has confirmed a Knowledge page and who has not

POST/api/v1/manage/knowledge/acknowledgements/status

const result = await shuffl.knowledge.acknowledgements.status({
  "sourceId": "<sourceId>"
});
Request fields (1)
  • sourceId string required
Response object

The response is object.

knowledge.acknowledgements.close

Stop asking people to confirm this page

POST/api/v1/manage/knowledge/acknowledgements/close

const result = await shuffl.knowledge.acknowledgements.close({
  "sourceId": "<sourceId>",
  "confirm": "knowledge.acknowledgements.close",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • sourceId string required
  • confirm "knowledge.acknowledgements.close" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • closed boolean required

knowledge.acknowledgements.remind

Message the people who have not confirmed this page yet

POST/api/v1/manage/knowledge/acknowledgements/remind

const result = await shuffl.knowledge.acknowledgements.remind({
  "sourceId": "<sourceId>",
  "confirm": "knowledge.acknowledgements.remind",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • sourceId string required
  • confirm "knowledge.acknowledgements.remind" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • reminded number required
    • waiting number required

knowledge.acknowledgements.request

Ask the people who can read this page to confirm they read it, and message them

POST/api/v1/manage/knowledge/acknowledgements/request

const result = await shuffl.knowledge.acknowledgements.request({
  "sourceId": "<sourceId>",
  "confirm": "knowledge.acknowledgements.request",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • notify false | true optional
  • sourceId string required
  • confirm "knowledge.acknowledgements.request" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • asked number required
    • audience null | "admins" | "directory" | "everyone" required
    • fresh boolean required
    • notified number required
    • waiting number required

knowledge.connections.browse

List documents a connected Knowledge source can see

POST/api/v1/manage/knowledge/connections/browse

const result = await shuffl.knowledge.connections.browse({
  "connectionId": "<connectionId>"
});
Request fields (4)
  • connectionId string required
  • cursor null | string optional
  • parent null | string optional
  • query string optional
Response object
  • items object[] required
    • id string required
    • kind "document" | "folder" required
    • location null | string required
    • modifiedAt null | string required
    • title string required
  • next null | string required

knowledge.connections.list

List connected Knowledge providers

POST/api/v1/manage/knowledge/connections/list

const result = await shuffl.knowledge.connections.list();
Request fields (none)

This operation takes no input.

Response object
  • catalog object[] required
    • auth object required
      • Option 1 object optional
        • kind "oauth" required
        • steps string[] required
      • Option 2 object optional
        • fields object[] required
        • kind "api_token" required
        • steps string[] required
      • Option 3 object optional
        • kind "url" required
    • availability object required
      • Option 1 object optional
        • state "available" required
      • Option 2 object optional
        • note string required
        • state "partner_pending" required
      • Option 3 object optional
        • note string optional
        • state "coming_soon" required
    • blurb string required
    • capabilities object required
      • browse boolean required
      • changeDetection "content" | "revision" required
      • formats string required
      • paste boolean required
      • picker null | "google" required
    • category "drive" | "hris" | "web" | "wiki" required
    • configured boolean required
    • docsHref string optional
    • id "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "sharepoint" | "website" required
    • name string required
    • slug string required
  • connections object[] required
    • accountId string required
    • accountLabel string required
    • canUse boolean required
    • connectedBy string required
    • createdAt string (date-time) required
    • id string required
    • provider "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "sharepoint" | "website" required
    • revision number required
    • revokedAt null | string (date-time) required
    • teamId string required

knowledge.connections.requests

List requests to connect a Knowledge source

POST/api/v1/manage/knowledge/connections/requests

const result = await shuffl.knowledge.connections.requests();
Request fields (none)

This operation takes no input.

Response object
  • requests object[] required
    • createdAt string (date-time) required
    • name string required

knowledge.connections.connect

Connect a Knowledge provider with a token

POST/api/v1/manage/knowledge/connections/connect

const result = await shuffl.knowledge.connections.connect({
  "fields": null,
  "provider": "bamboohr",
  "confirm": "knowledge.connections.connect",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • fields object required
  • provider "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "sharepoint" | "website" required
  • confirm "knowledge.connections.connect" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • id string required
    • revision number required

knowledge.connections.disconnect

Disconnect a knowledge provider

POST/api/v1/manage/knowledge/connections/disconnect

const result = await shuffl.knowledge.connections.disconnect({
  "connectionId": "<connectionId>",
  "expectedRevision": 0,
  "confirm": "knowledge.connections.disconnect",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • connectionId string required
  • expectedRevision number required
  • confirm "knowledge.connections.disconnect" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • disconnected boolean required

knowledge.connections.request

Ask an administrator to connect a Knowledge source

POST/api/v1/manage/knowledge/connections/request

const result = await shuffl.knowledge.connections.request({
  "name": "<name>",
  "requestKey": "a-new-unique-key"
});
Request fields (2)
  • name string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • requests object[] required
      • createdAt string (date-time) required
      • name string required

knowledge.handbook.export

Download the pages published to everyone as one handbook, in Markdown

POST/api/v1/manage/knowledge/handbook/export

const result = await shuffl.knowledge.handbook.export();
Request fields (none)

This operation takes no input.

Response object
  • generatedAt string (date-time) required
  • leftOut object required
    • admins number required
    • groups number required
  • markdown string required
  • pages object[] required
    • body string required
    • effectiveAt string (date-time) required
    • id string required
    • publishedAt null | string (date-time) required
    • title string required
    • version number required
  • teamName string required

knowledge.policies.coverage

Check which common HR policies Knowledge covers

POST/api/v1/manage/knowledge/policies/coverage

const result = await shuffl.knowledge.policies.coverage();
Request fields (none)

This operation takes no input.

Response object
  • policies object[] required
    • id string required
    • source null | object required
      • id string required
      • title string required

knowledge.sources.get

Read a Knowledge source

POST/api/v1/manage/knowledge/sources/get

const result = await shuffl.knowledge.sources.get({
  "sourceId": "<sourceId>"
});
Request fields (2)
  • sourceId string required
  • versionId string optional
Response object
  • canManage boolean required
  • document object optional
    • checkedAt null | string (date-time) required
    • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
    • id string required
    • kind "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "sharepoint" | "upload" | "website" required
    • name string required
    • revision number required
  • source object required
    • archivedAt null | string (date-time) required
    • archivedBy null | string required
    • checkedAt null | string (date-time) required
    • connectionId null | string required
    • createdAt string (date-time) required
    • documentId null | string required
    • effectiveAt null | string (date-time) required
    • externalId null | string required
    • id string required
    • latestVersionId null | string required
    • ownerId string required
    • publishedAt null | string (date-time) required
    • publishedAudience null | "admins" | "directory" | "everyone" required
    • publishedAudienceRules object required
      • roles "individual_contributors" | "managers"[] optional
      • units string[] optional
    • publishedBy null | string required
    • publishedVersionId null | string required
    • reviewAt null | string (date-time) required
    • revision number required
    • sectionKey null | string required
    • syncStatus null | "current" | "draft" | "error" | "removed" | "unavailable" required
    • teamId string required
    • updatedAt string (date-time) required
    • withdrawalReason null | "access_lost" | "hr" required
    • withdrawnAt null | string (date-time) required
  • sync object optional
    • failures number required
    • lastAttemptAt null | string (date-time) required
    • nextAttemptAt string (date-time) required
  • version object required
    • audience "admins" | "directory" | "everyone" required
    • audienceRules object required
      • roles "individual_contributors" | "managers"[] optional
      • units string[] optional
    • body string required
    • contentHash string required
    • createdAt string (date-time) required
    • createdBy string required
    • effectiveAt string (date-time) required
    • id string required
    • provenance object required
      • documentId string optional
      • edited false | true optional
      • externalId string optional
      • firstPage number optional
      • format "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" optional
      • importHash string optional
      • kind "article" | "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "pdf" | "sharepoint" | "upload" | "website" required
      • lastPage number optional
      • modifiedAt string optional
      • name string optional
      • section number optional
      • sectionKey string optional
      • sections number optional
      • uploadId string optional
    • reviewAt string (date-time) required
    • sourceId string required
    • teamId string required
    • title string required

knowledge.sources.history

List a Knowledge source's versions

POST/api/v1/manage/knowledge/sources/history

const result = await shuffl.knowledge.sources.history({
  "sourceId": "<sourceId>"
});
Request fields (1)
  • sourceId string required
Response object[]
  • audience "admins" | "directory" | "everyone" required
  • audienceRules object required
    • roles "individual_contributors" | "managers"[] optional
    • units string[] optional
  • contentHash string required
  • createdAt string (date-time) required
  • createdBy string required
  • effectiveAt string (date-time) required
  • id string required
  • provenance object required
    • documentId string optional
    • edited false | true optional
    • externalId string optional
    • firstPage number optional
    • format "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" optional
    • importHash string optional
    • kind "article" | "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "pdf" | "sharepoint" | "upload" | "website" required
    • lastPage number optional
    • modifiedAt string optional
    • name string optional
    • section number optional
    • sectionKey string optional
    • sections number optional
    • uploadId string optional
  • reviewAt string (date-time) required
  • sourceId string required
  • teamId string required
  • title string required

knowledge.sources.list

List Knowledge sources

POST/api/v1/manage/knowledge/sources/list

const result = await shuffl.knowledge.sources.list({});
Request fields (5)
  • cursor object optional
    • id string required
    • name string optional
    • updatedAt string (date-time) optional
  • query string optional
  • scope "active" | "archived" optional
  • sort "name" | "updated" optional
  • status "Access lost" | "Access restored" | "Changes need review" | "Check overdue" | "Draft" | "Needs review" | "Published" | "Removed from source" | "Review due soon" | "Scheduled" | "Sync needs attention" | "Withdrawn" | "all" | "attention" optional
Response object
  • archived number required
  • canManage boolean required
  • counts object required
    • Access lost number optional
    • Access restored number optional
    • Changes need review number optional
    • Check overdue number optional
    • Draft number optional
    • Needs review number optional
    • Published number optional
    • Removed from source number optional
    • Review due soon number optional
    • Scheduled number optional
    • Sync needs attention number optional
    • Withdrawn number optional
  • needsAttention number required
  • nextCursor null | object required
    • Option 1 object optional
      • id string required
      • name string required
      • updatedAt any optional
    • Option 2 object optional
      • id string required
      • name any optional
      • updatedAt string (date-time) required
  • rows object[] required
    • source object required
      • archivedAt null | string (date-time) required
      • archivedBy null | string required
      • checkedAt null | string (date-time) required
      • connectionId null | string required
      • createdAt string (date-time) required
      • documentId null | string required
      • effectiveAt null | string (date-time) required
      • externalId null | string required
      • id string required
      • latestVersionId null | string required
      • ownerId string required
      • publishedAt null | string (date-time) required
      • publishedAudience null | "admins" | "directory" | "everyone" required
      • publishedAudienceRules object required
        • roles "individual_contributors" | "managers"[] optional
        • units string[] optional
      • publishedBy null | string required
      • publishedVersionId null | string required
      • reviewAt null | string (date-time) required
      • revision number required
      • sectionKey null | string required
      • syncStatus null | "current" | "draft" | "error" | "removed" | "unavailable" required
      • teamId string required
      • updatedAt string (date-time) required
      • withdrawalReason null | "access_lost" | "hr" required
      • withdrawnAt null | string (date-time) required
    • status "Access lost" | "Access restored" | "Changes need review" | "Check overdue" | "Draft" | "Needs review" | "Published" | "Removed from source" | "Review due soon" | "Scheduled" | "Sync needs attention" | "Withdrawn" required
    • version object required
      • audience "admins" | "directory" | "everyone" required
      • audienceRules object required
        • roles "individual_contributors" | "managers"[] optional
        • units string[] optional
      • contentHash string required
      • createdAt string (date-time) required
      • createdBy string required
      • effectiveAt string (date-time) required
      • id string required
      • provenance object required
        • documentId string optional
        • edited false | true optional
        • externalId string optional
        • firstPage number optional
        • format "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" optional
        • importHash string optional
        • kind "article" | "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "pdf" | "sharepoint" | "upload" | "website" required
        • lastPage number optional
        • modifiedAt string optional
        • name string optional
        • section number optional
        • sectionKey string optional
        • sections number optional
        • uploadId string optional
      • reviewAt string (date-time) required
      • sourceId string required
      • teamId string required
      • title string required
  • scope "active" | "archived" required

knowledge.sources.search

Search Knowledge sources by title

POST/api/v1/manage/knowledge/sources/search

const result = await shuffl.knowledge.sources.search({
  "query": "<query>"
});
Request fields (1)
  • query string required
Response object[]
  • body string required
  • id string required
  • sourceId string required
  • title string required

knowledge.sources.archive

Archive an unpublished knowledge source

POST/api/v1/manage/knowledge/sources/archive

const result = await shuffl.knowledge.sources.archive({
  "expectedRevision": 0,
  "sourceId": "<sourceId>",
  "confirm": "knowledge.sources.archive",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • expectedRevision number required
  • sourceId string required
  • confirm "knowledge.sources.archive" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • archived boolean required
    • revision number required

knowledge.sources.changeAudience

Change who can read this knowledge source

POST/api/v1/manage/knowledge/sources/changeAudience

const result = await shuffl.knowledge.sources.changeAudience({
  "audience": "admins",
  "expectedRevision": 0,
  "sourceId": "<sourceId>",
  "confirm": "knowledge.sources.changeAudience",
  "requestKey": "a-new-unique-key"
});
Request fields (6)
  • audience "admins" | "directory" | "everyone" required
  • audienceRules object optional
    • roles "individual_contributors" | "managers"[] optional
    • units string[] optional
  • expectedRevision number required
  • sourceId string required
  • confirm "knowledge.sources.changeAudience" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • published boolean required
    • source object required
      • archivedAt null | string (date-time) required
      • archivedBy null | string required
      • checkedAt null | string (date-time) required
      • connectionId null | string required
      • createdAt string (date-time) required
      • documentId null | string required
      • effectiveAt null | string (date-time) required
      • externalId null | string required
      • id string required
      • latestVersionId null | string required
      • ownerId string required
      • publishedAt null | string (date-time) required
      • publishedAudience null | "admins" | "directory" | "everyone" required
      • publishedAudienceRules object required
        • roles "individual_contributors" | "managers"[] optional
        • units string[] optional
      • publishedBy null | string required
      • publishedVersionId null | string required
      • reviewAt null | string (date-time) required
      • revision number required
      • sectionKey null | string required
      • syncStatus null | "current" | "draft" | "error" | "removed" | "unavailable" required
      • teamId string required
      • updatedAt string (date-time) required
      • withdrawalReason null | "access_lost" | "hr" required
      • withdrawnAt null | string (date-time) required

knowledge.sources.importConnected

Import a document from a connected Knowledge source

POST/api/v1/manage/knowledge/sources/importConnected

const result = await shuffl.knowledge.sources.importConnected({
  "connectionId": "<connectionId>",
  "externalId": "<externalId>",
  "confirm": "knowledge.sources.importConnected",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • connectionId string required
  • externalId string required
  • confirm "knowledge.sources.importConnected" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • changed boolean required
    • documentId string required
    • needsReview string[] required
    • sourceIds string[] required
    • status "completed" | "reading" | "unchanged" required
    • uploadId null | string required

knowledge.sources.importWebsite

Import a website page into Knowledge for review

POST/api/v1/manage/knowledge/sources/importWebsite

const result = await shuffl.knowledge.sources.importWebsite({
  "auth": {
    "type": "none"
  },
  "url": "<url>",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • auth object required
    • Option 1 object optional
      • type "none" required
    • Option 2 object optional
      • token string required
      • type "bearer" required
    • Option 3 object optional
      • password string required
      • type "basic" required
      • username string required
    • Option 4 object optional
      • header "api-key" | "x-api-key" | "x-auth-token" required
      • token string required
      • type "api_key" required
    • Option 5 object optional
      • clientId string required
      • clientSecret string required
      • type "cloudflare_access" required
  • url string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • changed boolean required
    • documentId string required
    • needsReview string[] required
    • sourceIds string[] required
    • status "completed" | "reading" | "unchanged" required
    • uploadId null | string required

knowledge.sources.publish

Publish this knowledge version to its audience

POST/api/v1/manage/knowledge/sources/publish

const result = await shuffl.knowledge.sources.publish({
  "expectedRevision": 0,
  "sourceId": "<sourceId>",
  "versionId": "<versionId>",
  "confirm": "knowledge.sources.publish",
  "requestKey": "a-new-unique-key"
});
Request fields (5)
  • expectedRevision number required
  • sourceId string required
  • versionId string required
  • confirm "knowledge.sources.publish" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null optional
    • archivedAt null | string (date-time) required
    • archivedBy null | string required
    • checkedAt null | string (date-time) required
    • connectionId null | string required
    • createdAt string (date-time) required
    • documentId null | string required
    • effectiveAt null | string (date-time) required
    • externalId null | string required
    • id string required
    • latestVersionId null | string required
    • ownerId string required
    • publishedAt null | string (date-time) required
    • publishedAudience null | "admins" | "directory" | "everyone" required
    • publishedAudienceRules object required
      • roles "individual_contributors" | "managers"[] optional
      • units string[] optional
    • publishedBy null | string required
    • publishedVersionId null | string required
    • reviewAt null | string (date-time) required
    • revision number required
    • sectionKey null | string required
    • syncStatus null | "current" | "draft" | "error" | "removed" | "unavailable" required
    • teamId string required
    • updatedAt string (date-time) required
    • withdrawalReason null | "access_lost" | "hr" required
    • withdrawnAt null | string (date-time) required

knowledge.sources.refresh

Refresh a Knowledge source from its connected provider

POST/api/v1/manage/knowledge/sources/refresh

const result = await shuffl.knowledge.sources.refresh({
  "connectionId": "<connectionId>",
  "externalId": "<externalId>",
  "refresh": {
    "documentId": "<documentId>",
    "expectedRevision": 0
  },
  "requestKey": "a-new-unique-key"
});
Request fields (5)
  • connectionId string required
  • externalId string required
  • refresh object required
    • documentId string required
    • expectedRevision number required
  • replaceLocalDraft false | true optional
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • changed boolean required
    • documentId string required
    • needsReview string[] required
    • sourceIds string[] required
    • status "completed" | "reading" | "unchanged" required
    • uploadId null | string required

knowledge.sources.restore

Restore an archived knowledge source

POST/api/v1/manage/knowledge/sources/restore

const result = await shuffl.knowledge.sources.restore({
  "expectedRevision": 0,
  "sourceId": "<sourceId>",
  "confirm": "knowledge.sources.restore",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • expectedRevision number required
  • sourceId string required
  • confirm "knowledge.sources.restore" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • archived boolean required
    • revision number required

knowledge.sources.save

Save a Knowledge source draft

POST/api/v1/manage/knowledge/sources/save

const result = await shuffl.knowledge.sources.save({
  "audience": "admins",
  "body": "<body>",
  "effectiveAt": "2026-11-02T09:00:00.000Z",
  "expectedRevision": 0,
  "reviewAt": "2026-11-02T09:00:00.000Z",
  "sourceId": "<sourceId>",
  "title": "<title>",
  "requestKey": "a-new-unique-key"
});
Request fields (9)
  • audience "admins" | "directory" | "everyone" required
  • audienceRules object optional
    • roles "individual_contributors" | "managers"[] optional
    • units string[] optional
  • body string required
  • effectiveAt string (date-time) required
  • expectedRevision number required
  • reviewAt string (date-time) required
  • sourceId string required
  • title string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • source object required
      • archivedAt null | string (date-time) required
      • archivedBy null | string required
      • checkedAt null | string (date-time) required
      • connectionId null | string required
      • createdAt string (date-time) required
      • documentId null | string required
      • effectiveAt null | string (date-time) required
      • externalId null | string required
      • id string required
      • latestVersionId null | string required
      • ownerId string required
      • publishedAt null | string (date-time) required
      • publishedAudience null | "admins" | "directory" | "everyone" required
      • publishedAudienceRules object required
        • roles "individual_contributors" | "managers"[] optional
        • units string[] optional
      • publishedBy null | string required
      • publishedVersionId null | string required
      • reviewAt null | string (date-time) required
      • revision number required
      • sectionKey null | string required
      • syncStatus null | "current" | "draft" | "error" | "removed" | "unavailable" required
      • teamId string required
      • updatedAt string (date-time) required
      • withdrawalReason null | "access_lost" | "hr" required
      • withdrawnAt null | string (date-time) required
    • version object required
      • audience "admins" | "directory" | "everyone" required
      • audienceRules object required
        • roles "individual_contributors" | "managers"[] optional
        • units string[] optional
      • body string required
      • contentHash string required
      • createdAt string (date-time) required
      • createdBy string required
      • effectiveAt string (date-time) required
      • id string required
      • provenance object required
        • documentId string optional
        • edited false | true optional
        • externalId string optional
        • firstPage number optional
        • format "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" optional
        • importHash string optional
        • kind "article" | "bamboohr" | "box" | "confluence" | "dropbox" | "google_drive" | "guru" | "notion" | "pdf" | "sharepoint" | "upload" | "website" required
        • lastPage number optional
        • modifiedAt string optional
        • name string optional
        • section number optional
        • sectionKey string optional
        • sections number optional
        • uploadId string optional
      • reviewAt string (date-time) required
      • sourceId string required
      • teamId string required
      • title string required

knowledge.sources.withdraw

Withdraw a published Knowledge source

POST/api/v1/manage/knowledge/sources/withdraw

const result = await shuffl.knowledge.sources.withdraw({
  "expectedRevision": 0,
  "sourceId": "<sourceId>",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • expectedRevision number required
  • sourceId string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • withdrawn boolean required

knowledge.sources.write

Write a Knowledge page with Mello from its title and a request; nothing is saved

POST/api/v1/manage/knowledge/sources/write

const result = await shuffl.knowledge.sources.write({
  "confirm": "knowledge.sources.write",
  "requestKey": "a-new-unique-key"
});
Request fields (6)
  • body string optional
  • kind "article" | "company-values" optional
  • prompt string optional
  • title string optional
  • confirm "knowledge.sources.write" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • body string required
    • title string required

knowledge.templates.facts

Read what Shuffl knows that policy templates ask for

POST/api/v1/manage/knowledge/templates/facts

const result = await shuffl.knowledge.templates.facts();
Request fields (none)

This operation takes no input.

Response object
  • companyName null | string required
  • countries string[] required
  • holidaysTitle null | string required
  • hrContact null | string required
  • hrRequests boolean required

knowledge.templates.draft

Draft a policy template with Mello, researching each value; nothing is saved

POST/api/v1/manage/knowledge/templates/draft

const result = await shuffl.knowledge.templates.draft({
  "body": "<body>",
  "template": "acceptable-use",
  "title": "<title>",
  "confirm": "knowledge.templates.draft",
  "requestKey": "a-new-unique-key"
});
Request fields (8)
  • body string required
  • checks object[] optional
    • place string required
    • text string required
  • notes string optional
  • template "acceptable-use" | "benefits" | "bereavement" | "code-of-conduct" | "company-holidays" | "company-values" | "disciplinary-and-grievance" | "employee-privacy" | "equal-opportunity" | "expenses" | "health-and-safety" | "jury-duty" | "leave-of-absence" | "leaving-the-company" | "paid-time-off" | "parental-leave" | "performance" | "raising-concerns" | "sick-leave" | "travel" | "working-hours" required
  • title string required
  • website string optional
  • confirm "knowledge.templates.draft" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • body string required
    • choices object[] required
      • basis "company" | "law" | "typical" required
      • source null | object required
        • title string required
        • url string required
      • topic string required
      • value string required
    • placeholders number required
    • researched boolean required
    • sources object[] required
      • title string required
      • url string required
    • title string required

knowledge.uploads.get

Read the progress of a Knowledge file upload

POST/api/v1/manage/knowledge/uploads/get

const result = await shuffl.knowledge.uploads.get({
  "uploadId": "<uploadId>"
});
Request fields (1)
  • uploadId string required
Response object
  • byteSize number required
  • canRetry boolean required
  • chunkBytes number required
  • chunkCount number required
  • documentId string required
  • error null | string required
  • errorCode null | "access" | "encrypted" | "interrupted" | "no_text" | "ocr_failed" | "ocr_limit" | "ocr_unavailable" | "quota" | "too_many_pages" | "unreadable" | "unsupported" required
  • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
  • id string required
  • name string required
  • ocrPages number required
  • ocrRead number required
  • pageCount null | number required
  • pagesRead number required
  • received number[] required
  • sourceIds string[] required
  • status "completed" | "failed" | "parsing" | "queued" | "uploading" required
  • updatedAt string required

knowledge.uploads.appendPart

Upload the next part of a Knowledge file

POST/api/v1/manage/knowledge/uploads/appendPart

const result = await shuffl.knowledge.uploads.appendPart({
  "base64": "<base64>",
  "part": 0,
  "uploadId": "<uploadId>",
  "requestKey": "a-new-unique-key"
});
Request fields (5)
  • base64 string required
  • part number required
  • sha256 string optional
  • uploadId string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • byteSize number required
    • canRetry boolean required
    • chunkBytes number required
    • chunkCount number required
    • documentId string required
    • error null | string required
    • errorCode null | "access" | "encrypted" | "interrupted" | "no_text" | "ocr_failed" | "ocr_limit" | "ocr_unavailable" | "quota" | "too_many_pages" | "unreadable" | "unsupported" required
    • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
    • id string required
    • name string required
    • ocrPages number required
    • ocrRead number required
    • pageCount null | number required
    • pagesRead number required
    • received number[] required
    • sourceIds string[] required
    • status "completed" | "failed" | "parsing" | "queued" | "uploading" required
    • updatedAt string required

knowledge.uploads.complete

Finish a Knowledge file upload and start reading it

POST/api/v1/manage/knowledge/uploads/complete

const result = await shuffl.knowledge.uploads.complete({
  "uploadId": "<uploadId>",
  "requestKey": "a-new-unique-key"
});
Request fields (2)
  • uploadId string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • byteSize number required
    • canRetry boolean required
    • chunkBytes number required
    • chunkCount number required
    • documentId string required
    • error null | string required
    • errorCode null | "access" | "encrypted" | "interrupted" | "no_text" | "ocr_failed" | "ocr_limit" | "ocr_unavailable" | "quota" | "too_many_pages" | "unreadable" | "unsupported" required
    • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
    • id string required
    • name string required
    • ocrPages number required
    • ocrRead number required
    • pageCount null | number required
    • pagesRead number required
    • received number[] required
    • sourceIds string[] required
    • status "completed" | "failed" | "parsing" | "queued" | "uploading" required
    • updatedAt string required

knowledge.uploads.create

Start uploading a file to Knowledge

POST/api/v1/manage/knowledge/uploads/create

const result = await shuffl.knowledge.uploads.create({
  "name": "<name>",
  "sha256": "<sha256>",
  "size": 0,
  "requestKey": "a-new-unique-key"
});
Request fields (5)
  • mime string optional
  • name string required
  • sha256 string required
  • size number required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • byteSize number required
    • canRetry boolean required
    • chunkBytes number required
    • chunkCount number required
    • documentId string required
    • error null | string required
    • errorCode null | "access" | "encrypted" | "interrupted" | "no_text" | "ocr_failed" | "ocr_limit" | "ocr_unavailable" | "quota" | "too_many_pages" | "unreadable" | "unsupported" required
    • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
    • id string required
    • name string required
    • ocrPages number required
    • ocrRead number required
    • pageCount null | number required
    • pagesRead number required
    • received number[] required
    • sourceIds string[] required
    • status "completed" | "failed" | "parsing" | "queued" | "uploading" required
    • updatedAt string required

knowledge.uploads.retry

Retry reading a Knowledge file that failed

POST/api/v1/manage/knowledge/uploads/retry

const result = await shuffl.knowledge.uploads.retry({
  "uploadId": "<uploadId>",
  "requestKey": "a-new-unique-key"
});
Request fields (2)
  • uploadId string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • byteSize number required
    • canRetry boolean required
    • chunkBytes number required
    • chunkCount number required
    • documentId string required
    • error null | string required
    • errorCode null | "access" | "encrypted" | "interrupted" | "no_text" | "ocr_failed" | "ocr_limit" | "ocr_unavailable" | "quota" | "too_many_pages" | "unreadable" | "unsupported" required
    • format null | "docx" | "html" | "markdown" | "pdf" | "pptx" | "text" required
    • id string required
    • name string required
    • ocrPages number required
    • ocrRead number required
    • pageCount null | number required
    • pagesRead number required
    • received number[] required
    • sourceIds string[] required
    • status "completed" | "failed" | "parsing" | "queued" | "uploading" required
    • updatedAt string required