Confluence + Koji: Publish Living Research Pages the Whole Org Can Actually Find

The 60-second answer

Koji has no native Confluence app and emits no outbound webhooks, so pages do not appear on their own. Two routes work. The low-effort one: publish the Koji study report and embed or link its URL on a Confluence page - the report stays live and updates as interviews land, so the Confluence page never goes stale because it is pointing at the source rather than copying it. The full-sync route: pull the report and analysis through the Koji API, convert to Confluence storage format, and create or update a page through Confluence's REST API on a schedule.

Choose deliberately, because these two routes fail in opposite ways. A link cannot be read offline or searched by Confluence's index. A copy can be searched - and can quietly become wrong.

Why Confluence specifically

Atlassian reported over 300,000 customers in its Q4 FY25 shareholder letter, with Confluence customers >100K. For those organisations Confluence is not a documentation tool, it is where institutional memory is expected to live. If a research finding is not in Confluence, a sizeable part of the company will conclude it does not exist.

That creates a specific and under-appreciated risk. Research pages are unusually prone to rot: a page titled Onboarding research findings with no date carries exactly the same authority in search results whether it was written last week or in 2023. A stale research page is worse than a missing one, because it is confidently wrong and nobody questions it.

What belongs in Confluence

• The decision and its rationale - what you concluded and what changed because of it.
• The headline findings, with a handful of verbatim quotes.
• Scope and method - who you spoke to, how many, when, and what you did not cover.
• A link to the live Koji report for anyone who wants the full evidence.

What belongs in Koji

• Full transcripts. They are long, they contain personal data, and they are already searchable where they are.
• The evolving theme set. Themes shift as interviews land. A Confluence page that restates them is a snapshot that starts drifting immediately.
• Per-interview quality scores and structured answers. Useful for analysis, noise on a summary page.

The rule of thumb: Confluence holds the conclusion and the provenance link. Koji holds the evidence.

Setup: Koji to Confluence in four steps

Step 1 - Create a Confluence API token

Generate an API token from your Atlassian account settings and use it with your account email for basic auth against the Confluence Cloud REST API, or configure OAuth if your organisation requires it. Store the token as a secret; it carries your own Confluence permissions, so scope the account you use to the spaces this integration should touch.

Step 2 - Pull the material from Koji

For a page built from a whole study, the study report is the right source. For a page assembled interview by interview, call GET /api/v1/interviews/{id} with an API key in the Authorization: Bearer header. The key needs the interview:read permission and the endpoint requires an Interviews plan or higher. Respect the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers on every response.

If your team uses an MCP-capable assistant, there is a lighter path. Koji's MCP server exposes tools including koji_list_studies, koji_get_study, koji_get_report, koji_get_interviews, koji_get_transcript and koji_export_data, so an assistant can read the study directly and draft the Confluence page from it without any glue code at all.

Step 3 - Create or update the page, never duplicate it

Confluence's REST API needs the current version number to update a page, and increments it on write. The correct loop is: look the page up by title within the space, and if it exists, update at version.number + 1; if it does not, create it. Teams that skip the lookup end up with Onboarding research findings, Onboarding research findings (2) and Onboarding research findings FINAL, which is precisely the failure the integration was supposed to prevent.

Step 4 - Make the page state its own age

Put three things in a panel at the top of every generated page: the date the underlying study was last updated, the number of interviews it is based on, and a link to the live Koji report. This is the cheapest possible defence against rot. A reader who lands on the page in eight months can see immediately whether to trust it, and where to go for the current version.

How Koji handles this

• Every quote on the page is grounded. Each extracted theme, insight and quote carries a verbatim slice of a real respondent message, in the participant's original language. Items whose supporting quote cannot be matched back against the transcript are dropped server-side rather than published, so a page generated from Koji output cannot attribute a sentence to a customer who never said it.
• The report is a live surface, not an export. Linking to it from Confluence gives you a page whose evidence section updates itself as more interviews complete.
• All six structured question types come through machine-readable - open_ended, scale, single_choice, multiple_choice, ranking and yes_no - so a findings page can carry a real distribution rather than a hand-typed most people said.
• Study scope is recorded with the study, which is what makes an honest method section cheap to generate rather than something a researcher writes from memory a month later.
• The MCP server turns page drafting into a conversation with an assistant that can read the study directly.

Common mistakes

Pasting a snapshot and calling it a repository

A pasted summary is correct on the day it is pasted. Without a date and a link back to the source, it acquires permanent authority it has not earned. Always include both.

Letting pages rot silently

Nominate an owner per research space and review generated pages on a fixed cadence. Archive rather than delete, so links from old tickets do not break, and mark archived pages clearly in the title.

Copying full transcripts into Confluence

This is the most common governance mistake. Transcripts contain personal data, and copying them multiplies the number of systems holding it, usually into a space with far broader membership than the research tool. Link to the transcript; do not reproduce it.

Recreating the theme clustering by hand

Themes are clustered when the study report is generated. Retyping them into a Confluence table produces a second version that drifts from the first the moment another interview lands.

Governance

Confluence permissions are inherited from the space, and research spaces are frequently more open than teams assume. Before the first automated write, confirm who can read the target space and make sure that matches what participants were told. Where a study involves named customers or sensitive commercial detail, publish the conclusions to the open space and keep the evidence link pointing at Koji, where access is separately controlled.

Frequently asked questions

Does Koji have a native Confluence app?

No. There is no Koji app in the Atlassian Marketplace and no outbound webhook from Koji. You either link to a published Koji report from a Confluence page, or build a small job that reads from the Koji API and writes through Confluence's REST API.

Should I copy findings into Confluence or just link to the report?

Copy the conclusion, link the evidence. Confluence should hold what you decided, the headline findings with a few verbatim quotes, and the method and scope. The full transcripts and the evolving theme set should stay in Koji and be reached by link, so the page cannot drift out of date.

How do I stop the integration creating duplicate pages?

Look the page up by title within the space before writing. If it exists, update it using the current version number plus one, which is what the Confluence API requires. If it does not exist, create it. Skipping the lookup is what produces a trail of near-identical pages.

Can I use an AI assistant instead of writing code?

Yes. Koji's MCP server exposes tools including koji_list_studies, koji_get_study, koji_get_report, koji_get_interviews and koji_get_transcript, so an MCP-capable assistant can read a study directly and draft the Confluence page from it with no integration code.

What plan and permissions do I need?

The read endpoint needs an API key with the interview:read permission and an Interviews plan or higher. On the Confluence side you need an API token for an account with write access to the target space. The link-only route needs no Koji API access at all.

How do I keep a research page from becoming confidently wrong?

Put the study date, the interview count and a link to the live report in a panel at the top of every page, nominate an owner per space, and review on a cadence. A reader can then judge the page's age at a glance rather than assuming it is current.

Related Resources

• Structured Questions Guide - the six question types and what each returns
• Notion Research Integration - the same pattern for Notion
• Research Repository Guide - structuring findings so they get reused
• Insight Repository Methodology - keeping a repository trustworthy over time
• MCP Overview - reading Koji studies from an AI assistant
• Publishing and Sharing Reports - the link-only route
• Headless API Overview - the endpoints a full sync uses