> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guru

> Connect Guru to Serval to sync your Guru cards into a Serval knowledge base, search and read cards from workflows, track cards that need verification, and create new cards.

## 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

| Capability | Description |
| - | - |
| Sync cards into knowledge | **Sync Guru Cards to Knowledge** turns each card into a Markdown page in a read-only Serval knowledge base, with a link back to the card. The help desk agent searches these pages and cites them in its answers. |
| Search and read cards | **Search Guru Cards** finds cards by keyword. **Get Guru Card** opens one card by its ID or link. Both return the content as Markdown with the card's collection and verification status. |
| Browse collections | **List Guru Collections** returns each collection's ID, name and card count. Use the IDs to limit the sync to chosen collections. |
| Track verification | **List Guru Cards Needing Verification** lists cards whose verification has lapsed, most overdue first, with each card's owner. |
| Create cards | **Create Guru Card** adds a card to a collection. It asks for approval before it runs. |
| Guru API requests from workflows | Workflows and Catalyst can call the modeled Guru API through Serval's built-in Guru action. |
| Health checks | Four checks confirm the token signs in, can list and open cards, and which collections it can read. |

## Choose a token

Guru has two kinds of API token. The token decides what Serval can read and do.

| | User token | Collection token |
| - | - | - |
| Reads | Every card its Guru user can read | Cards in one collection |
| Writes | Can create cards, credited to its user | Read-only |
| **Username** to enter in Serval | The email address of the Guru user who owns the token | The collection's ID |
| Works with | All workflows | Sync, search and get card. Not List Guru Collections or Create Guru Card. |

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](https://developer.getguru.com/docs/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.

> [!WARNING]
>
> 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:

| Check | What it confirms |
| - | - |
| **Get Guru Token Owner** | The token signs in. Shows the Guru team, and the token's user or collection. |
| **List Guru Cards** | The token can list cards. A token that can see no cards passes, and says so. |
| **List Guru Collections** | Which collections the token can read, with their IDs and card counts. For a collection token, it names the one collection. |
| **Read a Guru Card** | The token can open a full card, and Serval can convert it to Markdown. It shows a short preview of the most recently changed card. |

> [!TIP]
>
> 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:

| Setting | Effect |
| - | - |
| `COLLECTION_IDS` | The collections to sync. Get the IDs from **List Guru Collections**. |
| `SYNC_ALL_COLLECTIONS` | Set to `true` to sync every collection the token can read instead. Every reader of the knowledge base then sees all of them. |
| `INCLUDE_CARDS_NEEDING_VERIFICATION` | Set to `true` to also sync cards whose verification has lapsed in Guru. Each one is marked as needing verification, so the agent does not present it as current. |

**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](https://docs.serval.com/sections/documentation/knowledge-base/custom-ingestion.md) 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.

> [!NOTE]
>
> 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

> [accordion] Get Guru Token Owner fails with an authentication error
>
> 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.

> [accordion] List Guru Collections or Create Guru Card fails
>
> These need a user token. A collection token can only read its own collection.

> [accordion] Some cards are missing from Serval
>
> 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.

> [accordion] Get Guru Card says the link is not a Guru card
>
> Pass a card link (`https://app.getguru.com/card/...`) or a card ID. Collection and board links are not cards.

> [accordion] A synced page looks different from the card in Guru
>
> 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](mailto:support@serval.com)** for assistance with your Guru integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.