Skip to main content

About Guru

Guru is a knowledge base where teams write short articles called cards, group them into collections, and verify them on a schedule. The Serval Guru integration connects to Guru’s API with a Guru API token and gives Serval access to your cards through its authenticated proxy. Authentication: HTTP Basic, with a Guru username and API token. Serval stores the token securely and attaches it to requests itself. The token is only sent to Guru’s API (api.getguru.com/api/v1/), and workflow code never sees it. Data sync: Guru cards sync into Serval through the Sync Guru Cards to Knowledge workflow, added as a custom knowledge source. Each sync reads the cards in the collections you choose: Serval adds new cards, updates changed ones, and removes cards that were archived or deleted in Guru. The other workflows read from Guru when they run.

What the Guru integration enables

Choose a token

Guru has two kinds of API token. The token decides what Serval can read and do. Use a collection token when Serval should see only one collection. Use a user token, ideally from a dedicated service user, for the full knowledge base, collection lists and card creation. Guru explains both in User tokens vs. collection tokens.

Get your credentials

1

Create the token in Guru

A Guru admin creates API tokens in Guru’s API access settings. Pick a user token or a collection token as described above.
2

Copy the token

Copy the token when Guru shows it, and store it securely.
3

Check what the token can read

Serval sees only what the token sees. For a user token, make sure its user can read every collection you want in Serval.
Treat the token like a password. If it is shared or exposed, revoke it in Guru and create a new one.

Connect in Serval

1

Add a Guru connection

In Serval, open the Guru integration and start a new connection.
2

Enter the username and token

Enter the username from the table above in Username, and paste the token into API token.
3

Submit and run the health checks

Submit the form, then run the health checks below.
To rotate the token later, edit the connection and paste the new token. Leaving a field untouched keeps its saved value.

Verifying the connection

Run the integration’s health checks from the integration page:
Passing checks prove the token works. Which cards Serval sees still depends on what the token can read in Guru.

Sync Guru cards into knowledge

1

Install the sync workflow

From the Guru integration, install Sync Guru Cards to Knowledge and publish it.
2

Choose what to sync

The workflow does not run until you choose collections. Edit the settings at the top of the installed workflow and publish again:
3

Add it as a custom knowledge source

Open Knowledge, select the Knowledge Sources tab, click Manage sources, and choose Add custom knowledge source on the Available tab. Name the source (for example, Guru), enter getguru.com as the logo, and select Sync Guru Cards to Knowledge. See Building Custom Ingestion Workflows for the other settings.
4

Run the first sync

Click Sync now on the new source. When it finishes, your cards appear under From your apps in the Knowledge sidebar. Ask the agent a question a Guru card answers, and check that it cites the card.
Each synced page links back to the card in Guru. Private cards, cards with no content and archived cards are skipped.

Workflows

Install these from the Guru integration. They are grouped into three bundles. Knowledge Sync
  • Sync Guru Cards to Knowledge: Runs as a custom knowledge source, as described above. No approval.
Card Lookups
  • Search Guru Cards: Takes a search query and returns up to 10 matching cards with title, link, collection, verification status and Markdown content. Long cards are cut at 8,000 characters and marked as truncated. No approval.
  • Get Guru Card: Takes a card ID or a link such as https://app.getguru.com/card/... and returns the full card as Markdown, with its owner and verification dates. No approval.
  • List Guru Collections: Returns each readable collection’s ID, name and card count. Needs a user token. No approval.
Card Management
  • List Guru Cards Needing Verification: Returns cards marked stale or needing verification, earliest due date first, with each card’s owner. Optionally limit it to one collection ID. No approval.
  • Create Guru Card: Takes a title, content (Markdown or HTML) and a collection ID, and creates the card shared with the Guru team. Turn off Share with team to keep it private to its owner. Needs a user token, and asks the installer for approval before each run.
Guru credits a new card to the owner of the connected token. Cards created through Serval show that user as the author, not the person who asked Serval. Use a dedicated service user if you want those cards to be easy to tell apart.

Limits

  • Permissions are not mirrored: Serval does not copy Guru’s card or collection permissions. Synced cards follow the visibility of the Serval knowledge base they land in. List only collections that are safe for every reader in COLLECTION_IDS, or connect with a collection token for a collection that is safe to share.
  • Full syncs only: Every sync reads all cards the token can see and keeps the chosen ones. A very large Guru account takes longer to sync.
  • Verification stays in Guru: Serval reads verification state; owners still verify cards in Guru.

Gotchas and troubleshooting

Check the username. A user token needs the email of the Guru user who owns it. A collection token needs the collection ID, not the collection’s name.
These need a user token. A collection token can only read its own collection.
The sync reads only cards the token can see, and skips private, archived and empty cards. Check the token’s access in Guru, then check COLLECTION_IDS, SYNC_ALL_COLLECTIONS and INCLUDE_CARDS_NEEDING_VERIFICATION in the sync workflow.
Serval converts card HTML to Markdown and keeps headings, lists, links, images, tables and code. Embedded videos and other rich blocks are dropped. Open the source link on the page to see the original card.

Need help? Contact support@serval.com for assistance with your Guru integration.