RFC-156: Rovo Search and Knowledge Sources

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Summary

Rovo Search gives Atlassian users AI-enhanced search across Jira, Confluence and connected third-party tools. Today, Forge apps can’t use it. This RFC proposes a new Forge API, requestRovoSearch(), that lets apps run Rovo Search from their backend, together with knowledge sources: an admin control that decides which content an app is allowed to search.

Rovo Search is generally superior to regular JQL/CQL keyword search because it returns semantic+keyword results with cross-product ML-based ranking. This means results better match the intent of the query.

  • Publish: 13 Nov 2026

  • Discuss: 27 Nov 2026

  • Resolve: 11 Dec 2026

Problem

Many Forge apps need to find relevant content before they can do something useful: enrich a ticket, detect a duplicate, route a request or provide context for an agent. Today, developers have to:

  • Call product-specific search APIs (for example, JQL and CQL) one at a time and merge the results themselves.

  • Build their own relevance ranking on top of keyword search.

  • Can’t search content from third-party sources that customers have connected to Rovo.

Proposal

  1. A new requestRovoSearch() function in the Forge API, available from resolvers and other backend functions, which runs a single cross-product Rovo Search query and returns ranked results.

  2. A new read:knowledge:rovo scope that an app must declare in its manifest to use Rovo Search.

  3. Knowledge sources for Forge apps: site admins choose which sources (for example, specific Confluence spaces, Jira projects or connected third-party tools) an installed app can search. This builds on the same knowledge source experience customers already use for Rovo Studio agents.

API shape

Request

const { results, errors, totalCount, nextCursor, hasMore } = await api.asUser().requestRovoSearch({
  query: "Q3 roadmap planning",
  first: 10,
  after: null,  // pass nextCursor from previous response to paginate
  entities: [   //optional: defaults to all available
    "confluence:page",
    "confluence:blogpost",
    "slack:message",
  ],
  filters: { //Strong typing to make query building easy
    commonFilters: {
      range: {
        lastModified: {
          gt: "2026-07-04T00:00:00Z",
        },
      },
    },
    jiraFilters: {
      projects: ['PROJ']
    }
  },
});

Response

{
  errors: null,
  results: [
    {
      title: "Q3 Roadmap Planning — Ecosystem",
      url: "https://abc.atlassian.net/wiki/spaces/ECO/pages/123456",
      snippet: "This page outlines key deliverables for Q3...",
      type: "confluence:page",
      id: "ari:cloud:confluence:<cloudId>:page/10234",
    },
    {
      title: "PROJ-669 – E2E test ownership restructure",
      url: "https://abc.atlassian.net/browse/PROJ-669",
      snippet: "Tracks the change in ownership model for ful...",
      type: "jira:issue",
      id: "ari:cloud:jira:<cloudId>:issue/10234",
    },
    {
      title: "John Smith in #proj-abc",
      url: "https://abc.enterprise.slack.com/archives/C0AQ83C5YD9/p17888...",
      text: "Here's an update about our roadmap planning for Q3...",
      type: "slack:message",
      id: "ari:cloud:graph::message/activation/a436116f-…/3e8a24ab-…",
    }
  ],
  totalCount: 47,
  nextCursor: "eyJvZmZzZXQiOjEwfQ==",
  hasMore: true,
}

Each result includes either text or snippet:

  • text: the full content of the item, in plain text. It’s returned when the full content is available from search (e.g. slack:message).

  • snippet: an excerpt relevant to the query, for items whose full content isn’t returned (e.g. confluence:page, jira:issue). To get the full content, call the relevant API with the ID.

Partial results and errors

Because one query searches several products, a failure in one product doesn’t fail the whole request. For example, if the caller can’t search Confluence, you still get Jira results:

{
  results: [
    {
      title: "PROJ-669 – E2E test ownership restructure",
      url: "https://product-fabric.atlassian.net/browse/PROJ-669",
      snippet: "Tracks the change in ownership model for ful...",
      type: "jira:issue",
      id: "ari:cloud:jira:<cloudId>:issue/10234",
    },
  ],
  errors: [
    {
      message: "Caller is not authorized to search Confluence",
      statusCode: 403,
      product: "confluence",
      integration: null,
    },
  ],
  totalCount: 17,
  nextCursor: null,
  hasMore: false,
}

Manifest

permissions:  
  scopes:   
  - read:knowledge:rovo

Knowledge sources and permissions

An app can only search content that passes all of these checks:

  1. Scope: the app declares read:knowledge:rovo in its manifest.

  2. Knowledge sources: a site admin has selected the sources the app may search. By default, an app has no knowledge sources until an admin enables them.

  3. Request: the sources and entity types the app asks for in requestRovoSearch().

  4. Content permissions: existing per-item permissions still apply. For example, a user who can see one Jira work item but not another only gets results for the one they can see.

In other words, the sources an app searches are:

admin-selected knowledge sources ∩ sources requested in the API call ∩ sources visible to user

Admins will configure knowledge sources from the app’s admin settings, using the same source picker that’s used for Rovo Studio agents today.

asUser and asApp

requestRovoSearch() supports both asUser() and asApp().

  • asUser() searches with the permissions of the user who invoked the app. Use this wherever there’s a signed-in user.

  • asApp() searches with the app’s own permissions. This is needed for modules that run without a signed-in user, such as scheduled triggers, event triggers, web triggers and Jira workflow post functions. In this case, restricted pages can not be searched.

Example use cases

Example 1: Ticket enrichment

A Jira Service Management app runs when a request is created, searches Confluence for related runbooks and known issues, and adds links to the request so agents can resolve it faster.

Example 2: Duplicate detection

A Jira app runs when a work item is created, searches for similar open work items in the same project and flags likely duplicates.

Example 3: Cross-product knowledge for Forge Rovo agents

A Forge app exposes an action that calls requestRovoSearch() to find relevant pages and work items. Forge Rovo agents can use this action to answer questions using the customer’s own content, including connected third-party tools.

Asks

  1. Use cases: What would you build first, and for which customers? Which entity types and third-party sources matter most? Would you use asUser or require asApp?

  2. API shape: Does the request and response shape fit how you’d use search? What fields or filters are missing (for example, author, space, project, labels or content body)?

  3. Knowledge sources: Does admin-selected knowledge sources, defaulting to none, work for your customers? How would you explain the setup step to admins during onboarding?

How to give feedback

  • Comment directly on this RFC thread in the Atlassian Developer Community.

  • Share use cases, concerns and suggestions to help shape Rovo Search for Forge.

Although I can see the specific value this feature would bring (reducing individual product-calls for findings workitems / pages), I wonder what the overall value is compared to Rovo as a whole:
In our app we currently use Forge LLM to prompt AI about arbitrary requests regarding work-items / pages. With this Rovo Search, we would still need to do that, only the relatively small part of fetching relevant work-items / pages can be simplified. But what we actually want to do is cut out Forge LLM and directly prompt Rovo about arbitrary requests, without the need to fetch individual work-items / pages as an intermediate step.
So, I think my main question is: Do you have such general Rovo access for apps on the roadmap? Is this Rovo Search just a small-ish part of a larger picture I’m not seeing yet?

Focusing on the proposal itself, I wonder if/how configuring those “knowledge sources” overlaps with the existing functionality of Data Security Policies, because with those an org-admin can already restrict app access to certain spaces. I’m not clear what the distinction would be.

Thanks Andreas,

We are currently thinking about ways to unlock more Rovo functionality for Forge apps, this proposal is somewhat adjacent to that though.

The main difference here is that you get back structured search results, which you can’t get back from Rovo. That’s not as useful if you just want to feed the results straight into an agent, but is essential if you want to use the results in other ways e.g. iterating over them or displaying them in UI.

The other difference from JQL etc is that you get semantic matching, not just keyword - so results should be much better even if you were only searching Jira. For multi-product search, you get semantic + ML based relevance ranking. I will update the RFC to mention this.

Good point re Data Security Policies. We are still thinking about where knowledge source configuration will live and that is one option we will consider.

Hey Timothy! Some quick thoughts from me:

  1. Seems like this would be great to allow users to search and filter data they already are seeing in apps, to understand things, conditional on some of the points below.
  2. The filters part of the request should include the option to filter results by JQL. A lot of how users select their data depends on JQL, and lacking interoperability with it eliminates a lot of use cases. Something like filters.jiraFilters.jql would be perfect.
  3. The API should be accessible directly from the frontend, not backend-only. Most use cases I can think of for our app would happen directly in the user’s browser. Passing things through the backend would just increase costs (money, latency and security) for absolutely no reason.
  4. This needs to be paired with an API endpoint allowing the apps to discover what sources it actually has access to, and what sources exist but are not yet configured by the admin for the app. Otherwise the user experience is awful: The app would show an “intelligent search” function, and when the user tries it there are no results, for no clear reason. We couldn’t even tell them to ask their admin to change the configuration, because we don’t even know if there is anything to change. We can’t distinguish between “you don’t have access” and “there are no results for this particular search”.

+1 for direct frontend access please

Hi Timothy, thanks for this RFC :raising_hands:

Context: We build Refined Sites, which lets customers publish Confluence and JSM content as branded intranets, help centers and documentation sites for their end users. Search is one of the most-used features on those sites, and today we assemble it from CQL plus JSM knowledge base calls with our own ranking.

Rovo Search with connected sources would be a big improvement for our customers.

Use cases

  • Site search across Confluence pages and blogs, JSM knowledge base articles and request types, and connected sources (SharePoint, Google Drive and Slack come up most with our customers).
  • Answer suggestions on help center request forms (deflection).

We’d use asUser for signed-in employees. However, a large share of our traffic comes from JSM portal customers (unlicensed) and anonymous visitors on public sites. Could you clarify how asUser behaves for a portal-only customer accounts on the JSM side?

API shape

  • Will requestRovoSearch() be callable from Forge Remote?

Knowledge sources
Defaulting to none makes sense for trust. A few things would make onboarding work:

  • A read API for the app’s current knowledge sources, so we can tell admins in our own UI why results are limited.
  • Configuration from inside the app’s own admin experience, either a write API or an embeddable source picker we can open from our setup flow. Sending admins to a separate settings page mid-onboarding would likely lower adoption.

Happy to join a call or an EAP to explain more, we’d be a good early adopter for this.

Thanks for the feedback Bogdan,

  1. Currently the semantic jira search index does not evaluate JQL, therefore for us to support this we would need a two step process: semantic search then a second pass to filter results by the jql. This is finicky (see post-filtering), and specific to the use case (e.g. how many results get fetched before the jql filter gets applied), so I think we’d be inclined to have devs implement this logic in the app.

    Without JQL you get filtering on: lastModified date, created date, projectARIs, statusCategories, issueTypes, issueLabels, user ARIs (assignees etc)

    For more than this, the suggested pattern would be to

    • call requestRovoSearch to get initial ids
    • call requestJira with something like id IN (<ids>) AND (<custom JQL>)

    If there are one or two important JQL filters you think are missing, I can look into supporting those as typed filters

  2. It will be accessible in frontend for asUser calls

  3. Good point. I will take that on board.

Thanks for the feedback! Glad to hear this will help you improve your app.

Could you clarify how asUser behaves for a portal-only customer accounts on the JSM side?

Our goal is to support JSM portal-only customers with their normal permissions applied. They would see knowledge base content shared with them, for example.

Will requestRovoSearch() be callable from Forge Remote?

Not at first, because we don’t have a public http endpoint for rovoSearch. This is something we may look at down the track though. Is that a deal breaker for you?

A read API for the app’s current knowledge sources, so we can tell admins in our own UI why results are limited.

Bogdan also mentioned this and we will include something along these lines. Design TBC.

Configuration from inside the app’s own admin experience, either a write API or an embeddable source picker we can open from our setup flow. Sending admins to a separate settings page mid-onboarding would likely lower adoption.

A write API is probably not feasible but we can explore ways to have a config modal pop up in-app, but can’t guarantee that in v1. Suggested flow would be to link directly to the app config page which opens in a new tab.

Will definitely reach out when we are ready for EAP, thank you!

Thanks, that’s helpful!

The portal-only behaviour is exactly what we need.

On Forge Remote: for us it’s a blocker. Refined Sites runs on a remote backend, so without a remote-callable endpoint we can’t adopt Rovo Search, even though the use case fits well.

To make the ask concrete, we only need asUser from Forge Remote. Our Rovo Search use cases are signed-in users, either internal employees (licenced) or JSM portal customers on help centers. We’d keep our existing search for anonymous visitors on public sites, so we wouldn’t need asApp .

Is remote support something you could put on the roadmap for after v1? A rough timeline would help us plan.

On configuration: a direct link to the app config page in a new tab works for v1, especially combined with the read API, then we can ensure to guide and inform admins on our end.

Ok that’s good to know. A public endpoint is not likely in the near future, however there may be a workaround we could explore:

Create a web trigger that uses offline impersonation to call asUser(accountId).requestRovoSearch(). You could then call this from remote to get search results.

Would this work? If so, I can push to get offline impersonation supported in V1. There may be some restrictions e.g. on third party search results.

A webtrigger might work, but we have not investigated them or used them before as part of our Forge app, so we’re not sure about the caveats around using them.

However, adding a webtrigger will cause a major version upgrade (one that every customer needs to manually approve) so that might limit the adoption and add complexity on our end.

Getting Forge Remote support officially would be preferred on our end.