I had this really interesting experience with a customer of Podscan recently. They reached out saying they were having trouble integrating our API. Now, this wasn’t unusual – we get these requests occasionally. But what happened next completely changed my perspective.
I did what I usually do: recorded a quick Loom video walking through the basics – creating an API key, making that first request, showing how to search for podcasts and get episode listings. Just a simple five-minute guide to get them started.
Their response? “When I watched it, something clicked. You know, I’m not technical at all – I’m just using Claude and ChatGPT and Replit to build some integrations.”
That stopped me in my tracks. Here was someone with no technical background using AI tools to build what turned out to be a pretty sophisticated system: they were planning to download podcast episodes from our API, put them into a vector database, and use an LLM to generate insights and verify information.
The Shifting Landscape
This got me thinking about how dramatically things have changed. Traditionally, API documentation was written by technical people, for technical people. The people reading it were developers who knew exactly what they wanted to do – they were the bridge between their code and our product.
But now? We’re seeing a completely different kind of user. People who might not know what an API key is, who might never have made an HTTP request before, but who can use AI tools to build surprisingly complex solutions.
The Rise of Selfish Software
This reminded me of an article my friend Stefan showed me on every.to called “Selfish Software” with the tagline “Making software can be fun again if you build for the user you’re most eager to please: yourself.”
It’s about people building tiny pieces of non-generalizable software – tools that solve their specific problems without needing to be scalable or sellable. Just software that works for them, for their business, for their projects.
And here’s where it gets interesting: these makers aren’t necessarily developers. They’re people with problems to solve, using AI as their development partner.
The Documentation Challenge
This creates a fascinating challenge for those of us building APIs. Our documentation now needs to serve two masters:
- It needs to be technically precise enough for AI tools to generate working code
- It needs to be accessible enough for non-technical users to understand the basics
Think about it – we’ve never had to do this before. Previously, our documentation was split: human-readable docs for developers, and machine-readable specs like Swagger or OpenAPI for tools. Now we need something that works for both humans and AI, while being accessible to non-developers.
What We Can Learn from Stripe
Stripe, as usual, is ahead of the curve here. They’ve already started adapting their documentation for this new reality. They offer an LLM.txt file for their entire API docs – essentially a markdown file that helps AI systems understand their API structure. They’ve even added features like “Copy page as markdown” and direct links to open documentation in ChatGPT.
Making Documentation AI-Native
So what does this mean for those of us building APIs? Here are some practical steps we should consider:
First, we need more working examples. AI tools are particularly good at inferring patterns from complete, working code samples. These examples should go from request to response, clearly explained and ready to be adapted.
Second, we need to be more explicit about the basics. We can’t assume knowledge of REST APIs or HTTP requests. Remember, our users might be copying our entire documentation into ChatGPT to generate their integration code.
Finally, we need to think about the experience of non-technical decision makers. Imagine a manager who wants to quickly test if your API fits their needs. They should be able to click a button, have AI generate some test code, and see results immediately.
Looking Forward
This shift represents a fascinating democratization of technical implementation. We’re moving from a world where API integration was exclusively the domain of developers to one where anyone with a problem and access to AI tools can build solutions.
For those of us running software businesses, especially ones with API-first products, this is both a challenge and an opportunity. The challenge is adapting our documentation and onboarding to this new reality. The opportunity? A whole new audience of potential users who previously wouldn’t have considered using our APIs.
I think this is just the beginning. As AI tools become more sophisticated and accessible, we’ll need to keep evolving how we present our technical products to the world. The winners will be those who make their APIs not just powerful, but accessible to this new wave of AI-assisted builders.
