Confluence
Index and search Confluence documentation in Risotto
Connect your Confluence workspace to Risotto to make your documentation searchable through the AI assistant. Risotto indexes Confluence pages by space and keeps content up to date automatically via real-time webhooks.
Prerequisites
Before connecting Confluence, ensure:
- Confluence Cloud - You have a Confluence Cloud instance (e.g.
yourcompany.atlassian.net) - Atlassian Organization Admin - You have the
Organization adminrole to install apps. See Make someone an organization admin - Risotto Admin Access - You are an administrator in your Risotto organization
- Confluence API Token - You have an Atlassian API token for reading content. A classic token (
ATATT...) and a scoped token (ATSTT..., the kind a service account creates) both work. For a token on your own Atlassian account, click Create API token, not Create API token with scopes. See Service accounts and scoped tokens.
Install the Confluence App
Start installation
In your Risotto dashboard, go to Settings > Integrations and click the Confluence card. Find the Page updates card ("Reindexes a page when it changes in Confluence."). Click Install App on the card.
The Install Confluence Forge App dialog opens. Enter your Atlassian site URL (for example,
yourcompany.atlassian.net) and click Get install link. If the Jira Forge app is already connected, the dialog skips the URL: click Get install link to install the Confluence app on the same site.Approve permissions
The dialog lists three steps: open the Atlassian install page, review and approve the requested permissions, then return and click Continue. Click Open install page to open the Atlassian installation page in a new tab.
The Atlassian page for the risotto-confluence app (published by Risotto) lists the permissions it requires:
- Read Confluence detailed content
- Read Confluence content summary
- Write Confluence content
- Access and interact from outside of Atlassian
- Share data with 1 domain outside of Atlassian
Click Get app, choose the Confluence site to install it on, and click Install to add the Risotto app to your Confluence instance.
Complete setup
Return to the Risotto dialog and click Continue. A toast confirms "Confluence Forge app installed successfully", and the Page updates card shows a green Connected status, with a menu that holds Disconnect....
Create a Knowledge Index
After installing the app, add a space to start importing your Confluence content. Each space has its own API token.
Open the Knowledge tab
Go to Settings > Integrations and click the Confluence card. Open the Knowledge tab. In the Indexed spaces section, click Add space. If nothing is connected yet, the page shows a Confluence spaces row instead: click Index a space. The Index a space dialog opens.
Configure the index
The Index a space dialog shows these fields. Fill in the required ones:
Field Required Description Site URL Yes Your Confluence site URL (e.g. https://yourcompany.atlassian.net). Start it withhttps://. Risotto appends/wikiautomatically.Space key Yes The key of the Confluence space to index (e.g. ENG,DOCS). Enter the key only, not a page URL or path.Account email Yes Email address of the API token owner API token Yes Your Atlassian API token, stored as a credential vault entry. Classic and scoped (service account) tokens are both supported. Query No CQL query to filter which pages are indexed (e.g. label="documentation"). See Index one page or a set of pages.Department Org Admins and Managers: No. Others: Yes Restrict this index to a specific department. Org Admins and Managers can leave it at Organization-wide (no department restriction). Audience No Everyone (the default) or Assistant only. An enforced access boundary. Risotto names the index after the space key.
Start indexing
Click Index space. A toast confirms "Indexing job enqueued successfully", and the space appears at the top of the Indexed spaces list as a card that reads Indexing, with the number of pages indexed so far. The card has Pause while the job runs, and Cancel, Retry or Resume when it does not.
Create index on Knowledge > Indexes still adds a Confluence index too. Its Create Index dialog asks for the same details plus an Index name, and it is the only place to set Profile filters.
Index one page or a set of pages
An index covers one Confluence space. Use the Query field to narrow it to some of the pages in that space.
Risotto builds the full search itself. It always adds type = page and the Space key you entered, then appends your Query in parentheses. Enter only the extra filter:
| To index | Enter in Query |
|---|---|
| One page | id = 132579653. The page ID is the number after /pages/ in the page URL. |
| One page and every page under it | id = 132579653 OR ancestor = 132579653 |
| Every page with a label | label = "risotto". To add a page later, give it the label in Confluence and click Reindex. |
| Every page except those with a label | type = page AND label != "no-index" |
Do not add space clauses. Risotto sets the space. A space clause at the start of the Query can make the rest of the search invalid, and the index then fetches no pages.
Start the Query with a positive clause. Because Risotto puts your Query in parentheses, Confluence rejects a Query whose first clause is negative, such as NOT label = "no-index". To exclude pages, start with type = page, then add the negative clause with AND, as in the last row of the table.
When you create the index or save a new Query in Configure, Risotto sends the full search to Confluence once to check it. If Confluence rejects the Query, the save fails, Risotto does not store the Query, and the dashboard shows "Confluence rejected the Query (CQL) for this index. Check the Query syntax." Correct the Query and save again. If Risotto cannot reach Confluence for the check, for example because the credentials are wrong, it saves the Query without the check.
When you change the Query on an existing index (three-dot menu > Configure), Risotto saves the new filter but does not fetch pages again. Click Reindex in the same menu to apply it. Until then, the index keeps the pages it fetched before.
Real-time updates follow the Query. When a page changes, Risotto checks it against the query. A matching page is re-indexed. A page that no longer matches is removed from the index.
Monitoring Indexing Progress
After you add a space, monitor progress on the space's card on the Knowledge tab, or in the Indexing Jobs panel on the Knowledge > Indexes page:
- Processing: Currently indexing pages — shows page count and progress bar
- Paused: Indexing has been paused — click the retry button to resume
- Error: An issue occurred — check the error message and retry
Use the buttons next to the progress bar to pause a running job, retry a paused or failed job, or cancel a job. Cancel is unavailable while the job is processing: pause it first.
Configure an Existing Index
To update an index after creation:
- Navigate to Knowledge > Indexes
- Find your Confluence index in the table
- Click the three-dot menu (⋮) and select Configure
From the configuration dialog, you can:
- Update the Query (CQL) filter: Saving stores the new filter only. Click Reindex to apply it. See Index one page or a set of pages.
- Update API credentials: check the box, then enter the Email address and a new API token. Use it when your API token expires (tokens expire after one year)
- Change department assignment — Restrict or widen access to the indexed content
- Change the Base URL — Use this if your Atlassian site moved. Changes take effect on the next reindex.
On the Knowledge tab, you can also click the Site or Query value on the space's card, edit it, and click Save. Saving does not reindex: click Reindex in the card's menu to apply it. You can change the API token and the account email only with Configure... on Knowledge > Indexes.
Service accounts and scoped tokens
Atlassian issues two kinds of API token. A classic token starts with ATATT. A scoped token starts with ATSTT, and is the only kind an Atlassian service account can create. Risotto accepts both in the API token field.
Enter your site URL (for example, https://yourcompany.atlassian.net) as the Base URL for either kind of token. For a scoped token, Risotto sends its API calls through the Atlassian API gateway (api.atlassian.com) at index time. The stored Base URL stays your site URL, so page links and real-time updates keep working.
To fully refresh the index, click the three-dot menu and select Reindex. This re-processes all pages in the space.
How Content Stays Up to Date
The Confluence app receives real-time webhooks when pages are created, updated, or deleted. Risotto automatically re-indexes affected pages — no manual action is needed for ongoing updates.
Events handled automatically:
- Page created, updated, or published
- Page deleted, trashed, or restored
- Page archived or unarchived
Access Control
Department Restriction
Restrict who can search the Confluence index:
- When creating or editing the index, select a Department
- Only members of that department will see results from this index
Organization-Wide Access
Select "Organization-wide (no department restriction)" to allow all users to search the Confluence content.
Disconnecting Confluence
To disconnect, go to Settings > Integrations > Confluence, click Connected on the Page updates card, and choose Disconnect.... This removes the connection and stops updates to your indexed Confluence pages; you can reconnect at any time.
If your organization still has the legacy Connect app installed alongside the Forge app, the menu offers two options:
- Disconnect legacy Connect app... removes only the legacy Connect app. The Forge app stays connected and Confluence keeps working.
- Disconnect Confluence (all)... removes both apps and stops updates to your indexed pages.
Troubleshooting
App installation fails
- Ensure you have Organization admin permissions in Atlassian
- Confirm your Confluence instance is a Cloud instance (not Data Center or Server)
- Check that your Confluence site is accessible and not behind restrictive firewalls
Index creation fails
- Verify your API token is valid and the email address matches the token owner
- If you created the token for your own account with Create API token with scopes, create a new one with Create API token (no scopes). See Service accounts and scoped tokens
- Confirm the space key exists in your Confluence instance
- Check that the API token owner has read access to the target space
The index seems to hold the wrong page or the whole space
The Description link on the Indexes table always opens the space home page, even for an index that holds one page. Check the page count on the indexing job instead. If you changed the Query after the index was created, click Reindex from the three-dot menu. A saved query is not applied until the next reindex. See Index one page or a set of pages.
Pages not appearing in search results
- Verify the space key is correct
- Check any CQL filters that may be excluding pages
- Ensure the API token has read access to the space
- Allow time for large spaces to finish indexing — check the progress bar
Scoped token fails with a cloud id error
The index error says the site's cloud id could not be resolved. Open the index
configuration (three-dot menu > Configure) and check that Base URL is
your *.atlassian.net site URL. Save, then Reindex.
Index fails: Confluence rejected the API token when reading page content
The search for pages worked, but Confluence refused the first page read (HTTP 401). Risotto stops the job, because every page would fail in the same way. This occurs most often with a scoped token that can search but cannot read page content.
- Give the token a scope that reads page content, or create a new token.
- Open the index configuration (three-dot menu > Configure) and update the API token.
- Click Reindex.
Some pages are missing and admins get a Confluence Indexing Error notification
Confluence refused to show one page (HTTP 403 or 404). For example, the page is restricted, in the trash, or deleted. Risotto skips that page, counts it as failed, and indexes the other pages in the space. The notification says "Unable to read Confluence page" with the page ID and the space key. Risotto sends one notification for each space until an admin dismisses it.
If the page must be in the index, give the token owner view permission on the page, then click Reindex.
Index fails: Unable to access Confluence space
Confluence did not find the space, or the token owner cannot view it. Check the Space key in the index configuration and the token owner's permissions on the space, then click Reindex.
API token expired
- Atlassian API tokens expire after one year
- Open the index configuration (three-dot menu > Configure) and update your credentials
- Create a new token at id.atlassian.com
Real-time updates not working
- Verify the Confluence app is still installed in your Atlassian admin settings
- The Forge app handles webhook delivery automatically — no manual webhook configuration is required
- If updates are consistently delayed, try a manual reindex and contact support
Next Steps
After setting up your Confluence index:
- Test the integration using Knowledge > Playground
- Ask Risotto questions about your indexed content in Slack
- Monitor answer quality in the Analytics dashboard
- Add more spaces with Add space on the Knowledge tab
For additional help, contact support at support@tryrisotto.com.
Something wrong or missing? Report an issue · View as Markdown