Developer portals, originally designed for human users, are on the cusp of significant change. With generative AI fundamentally reshaping digital experiences, portals must adapt to meet new expectations—not just from users on the technical and business mindset spectrum, but regarding the AI tools that will increasingly mediate these interactions.
AI as (an intermediary) user persona
Creating user personas is a meaningful exercise that helps make sense of user intent within a specific context. Personas are an attempt to distill the complexity of human behavior into clear, actionable insights. It is also worth considering how AI tools interact with developer portals, and how their actions mimic or differ from human users.
AI tools, such as crawlers gathering large datasets for training purposes and AI mediated search; as well as agents performing tasks on behalf of users, introduce novel types of activity to developer portals.
People have gone from cautiously experimenting with AI to integrating it to their professional workflows as a productivity tool in their toolbox. A generative AI tool can now serve as an intermediary not only presenting users with a vast array of information but curating the most relevant results to enhance decision making.
This shift raises the question: does it make sense to consider AI tools as personas on developer portals?
AI’s impact on human users
AI tools can fulfil different functions and roles, although their contributions manifest differently from human users.
AI tools are often used to support discovery and evaluation. We might turn to AI-assisted search to cut through the noise and get straight to a curated list of results. By searching for a specific use case, they can save time wading through irrelevant content, lessening the cognitive load of the process.
In this context, AI functions as an extension of the user's cognitive processes, illustrating the concept of distributed cognition. At its core, distributed cognition means that knowledge and cognition are not limited to the individual’s mind, but they span across our social and physical environments, too. For example, a complex process like launching a marketing campaign requires coordinated effort and input from a range of individuals who bring their own unique experience and knowledge to the table. But how does this translate to human-AI cooperation in the context of API discovery, where AI and human users collaborate to achieve shared goals?
The human user asks for an API recommendation, to which the AI tool gathers data from web interfaces, APIs, and other sources to complete the research collaboratively. Then, the AI tool reads documentation and creates a suggestion for the most suitable API to use. It is ultimately up to the human user to act on the output, and often fact-check and refine the recommendation before taking action.
By delivering curated results, generating concise summaries, or performing actions on behalf of users, AI tools guide users through workflows. For example, a powerful AI chatbot trained on a portal’s documentation can save a developer one or several steps in their journey to grasp and master the documentation and create code that uses the documented interfaces.
We will now explore how AI is reshaping interactions within developer portals, enhancing discoverability and findability.
AI-assisted search
Developers are increasingly experimenting with AI-driven search to browse APIs, however, our in-house UX research shows that they still double-check the results and prefer recommendations from fellow industry professionals they trust. From a findability perspective, appearing in AI search results might become a priority in the future if developers gain greater trust and confidence in these tools' accuracy and reliability.
AI tools can now utilize retrieval-augmented generation (RAG) to scan vast datasets across the web and curate highly relevant answers for users. Unlike traditional search engines, which present a list of links for the user which require manual exploration, these AI tools go one step further: they summarize findings to lessen the cognitive load on users.
This could save developers the time they would normally spend on finding the right information that answers their questions, however, without appropriate guardrails in place, AI tools are still prone to “hallucinations”.
Company-sanctioned LLM chatbots
On developer portals, company-sanctioned LLM chatbots can pave the way for an enhanced user experience. By integrating an AI-powered chatbot optionally trained on an organization's content, pre-prompted to take advantage of structured documentation on developer portals, organizations can provide a more interactive way to find information, as well as decrease the number of support requests by offering immediate, context-aware guidance.
Company-sanctioned Large Language Model (LLM) chatbots eliminate some of the most pressing concerns around the application of AI. They mitigate data privacy risks by operating within a controlled environment, and they also offer chatbot operators complete control over the scope of the output. Another benefit is that unlike public LLMs that draw information from all over the web, company-sanctioned LLMs can be given a limited scope, making them highly accurate in their narrow field of “expertise” and decreasing the chance of hallucinations.
While a chatbot can be a safe and effective way to introduce an AI-assisted support solution on your portal, there are still some questions that you need to consider. How can you honor confidentiality obligations towards your clients when they are sharing information with the chatbot? How can you ensure accurate and up-to-date responses? As a general rule of thumb, transparent disclaimers and a continued commitment to users’ trust and data security are essential.
AI-ready API documentation
One way to serve AI personas on your developer portal is to make the content on your developer portal AI-ready. Regularly updated and well-maintained content is key to ensure that AI tools retrieve accurate and relevant information. This involves using structured formats, clear tagging, and consistent metadata to help AI identify and interpret documentation effectively. Additionally, providing comprehensive FAQs, step-by-step tutorials, and use cases can enhance the quality of answers AI tools generate for users.
A generative AI tool’s output is influenced significantly by the quality and structure of the data it consumes, as it does not differentiate accurate information from nonsense. AI tools can be more rigid in their learning processes, and they often cannot read “between the lines”, relying on the information even if it is incomplete or inaccurate. For this reason, the predictability and structure of the portal, such as standardized formats, well-documented endpoints, and machine-readable metadata, are essential. While human users can work through trial and error, AI systems depend on consistency and will fail to interpret information if the expected patterns are broken.
While some advocate for AI’s ability to make sense of “data lakes”, our experience shows that AI performs far better when working with well-structured content compared to unstructured, disorganized collections of documents. Experiments with structured data collections have consistently yielded successful results, whereas attempts to extract value from raw, unorganized data have often fallen short.
As for structure, the features that make documentation easily scannable and digestible for human users vastly overlap with what AI tools infer from documents. In general, machine scrapers benefit from elements that add context and clarity to content for easier identification. For example, metatags, link text, alt tags, and scannable lists all aid with classification. Accessibility is another shared benefit, since clear labels and properly tagged content makes it easier for both users with assistive technology and AI scrapers to navigate websites.
Serving both human and AI personas
Developer portals of the future might have to consider how to better serve not just human users but also the AI agents acting on their behalf. By ensuring that documentation is clear, consistent, and easy to consume for humans and machines alike, portals can cater to both spheres of interest.
One trend that is worth keeping an eye on is agentive design. Instead of working prompt-by-prompt, an AI agent iteratively attempts to solve a problem until it finishes a task. This can mean a massive increase in resource usage if content is unstructured or hard to access, so structure and consistency become even more important.

Would you like to stay updated on the effect of AI on developer portals? Our Developer Portals Newsletter delivers fresh insights straight to your inbox.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.