Heretto

Last updated: October 16, 2026

Connect Iris to Heretto to bring your published product documentation into the Knowledge Map and keep it current. Iris reads from a Heretto deployment through the Heretto Deploy API, so it only ever sees content you have published. Drafts in the CCMS never reach Iris, and Iris never writes anything back to Heretto.

Once connected, you can pick a section of your docs and tell Iris to keep it in sync. New topics appear in your Knowledge Map, edited topics are refreshed, and topics you unpublish are removed. Answers that draw on this content cite the published page on your docs portal.

Before you start

You need two things from a Heretto CCMS admin:

  1. A read-only Deploy API key. In Heretto, open the main menu, choose Deploy API, then New API Key and Simple API Key. A key scoped to the specific map you publish is enough.
  2. The Deployment ID of the deployment you publish to. In Heretto, open the main menu and choose Deployments.

If you are not the Heretto admin, the Heretto section in Iris has a ready-made email you can forward to them.

On the Iris side you need to be able to open Settings and Integrations.

Connect Heretto

  1. In Iris, go to Settings, then Integrations.
  2. Find Heretto and click Connect.
  3. Fill in the connection form:
    • Heretto environment URL: the address you use to sign in to Heretto, such as https://yourcompany.heretto.com.
    • Deployment ID: from the Deployments page in Heretto.
    • Deploy API key: the key your admin created.
    • Docs portal URL (optional): the public address of your docs portal, such as https://docs.yourcompany.com. Iris uses it so citations link to the published page.
    • Audience (optional): if your deployment serves different audiences, enter the one Iris should read as. Leave it blank to use the deployment's default audience.
  4. Click Connect.

Iris checks the key against your deployment right away. If the check fails, the most common causes are a key that belongs to a different deployment, a Deployment ID copied from the wrong environment, an environment URL that is not the one you sign in to, or an audience name the deployment does not have.

Once connected, the Heretto section shows the deployment name and ID, the last time Iris checked for new publishes, how many files have been synced, and how many sync rules are active.

Keep a section in sync

A sync rule tells Iris to watch one section of your docs and every published topic under it. You can create one from the Heretto section in Settings, or from the Knowledge Map.

  1. In Settings, then Integrations, open Heretto and click Add sync rule. From the Knowledge Map, click Add from Integrations and choose Heretto instead.
  2. Browse your deployment the way it is organized on your portal. Open the section you want and click Keep "section name" in sync. At the top level you can choose Keep the whole deployment in sync instead.
  3. In the Enable Heretto Sync window, pick at least one tag. Every topic Iris brings in through this rule gets these tags.
  4. Leave Import published topics now checked to import everything in the section immediately. If you clear it, Iris waits for the next publish before importing anything.
  5. Click Enable Sync.
Pick the tags once. Every topic under the section gets them, now and on future syncs.

Pick the tags once. Every topic under the section gets them, now and on future syncs.

The rule shows Syncing while the first import runs and Connected once it finishes. Large sections can take a few minutes.

After that, Iris checks the deployment for a new publish every hour. When it finds one, it adds new topics, refreshes topics that changed, and removes topics that are no longer published under that section. Topics that did not change are left alone, so a publish that touches a handful of pages does not re-process the whole section.

Tags you add to a synced file by hand in the Knowledge Map survive future syncs. To change the tags a rule applies to every file, open the rule's menu and choose Edit tags, then Save & re-sync.

From the same menu you can Sync now to check for a new publish immediately, Pause a rule, or Delete it. Deleting a rule keeps the files already in your Knowledge Map. They just stop updating.

Instant sync

Hourly checks are enough for most teams. If you want a publish to reach Iris within a minute or two, the Heretto section in Settings shows an Instant sync URL with a copy button.

Give that URL to whoever runs your publishing. Any system that can send a POST request after a publish finishes can call it: a Heretto CCMS publishing webhook, your CI pipeline, or an automation tool. The request needs no body and no login. The long token in the URL is the credential, so treat it like a password and keep it inside your team. Heretto CCMS publishing webhooks are turned on by Heretto support on request, so ask your Heretto admin to check with them.

If you disconnect and reconnect Heretto, the URL changes. Send the new one to whoever set up the call.

Import a few topics without a sync rule

You can also bring in individual topics once, without keeping them in sync.

  1. In the Knowledge Map, click Add from Integrations and choose Heretto.
  2. Browse to the topics you want and select them. Topics already in your Knowledge Map are marked so you do not import them twice.
  3. Pick tags, set an expiration date if you want one, and import.

Topics imported this way are not updated when you publish again. Use a sync rule for anything you expect to change.

Find Heretto content in the Knowledge Map

Files that came from Heretto show Heretto in the Source column. To see only those files, open the Source filter above the file list and choose Heretto.

Filter the Knowledge Map by source to see everything Iris has pulled from Heretto.

Filter the Knowledge Map by source to see everything Iris has pulled from Heretto.

Synced files cannot be refreshed or replaced by hand, because Heretto is the source of truth. Publish the change in Heretto and Iris picks it up on the next check.

Disconnect

In Settings, then Integrations, open Heretto and click Disconnect. Files already in your Knowledge Map stay there. Sync rules stay too, marked Disconnected, and start working again when you reconnect to the same deployment.

Related articles