When we launched the SellerMate Public API, we assumed the reader of our documentation would be a developer. Within a week it was clear that assumption was wrong, and fixing it changed how we think about docs entirely.

This is a short write-up of what we found, what we changed, and a checklist for anyone else shipping an API in 2026.

The reader is a model

Here is how our API actually gets discovered. An agency owner asks Claude or ChatGPT something like "can I pull my SellerMate data into a dashboard". The assistant says "check whether SellerMate has an API". The owner searches, finds our page, and pastes the link back into the chat. From that moment on, the human never reads the documentation. The model does.

So the question is not "is this clear to a developer". It is "what does a model see when it fetches this URL". And the answer, for our first version, was almost nothing.

What the model saw: 388 bytes

Our interactive reference was built on Scalar, a good tool that renders an OpenAPI spec into a browsable page with a try-it console. It looks great in a browser. But the HTML it serves is a shell: a title, a script tag pointing at the spec, and a bundle from a CDN. Everything you see is drawn by JavaScript after the page loads.

1curl -s https://api.sellermate.ai/public/v1/docs | wc -c
2# 388

A model fetching that page gets the title and nothing else. No tools, no parameters, no auth instructions. It would then either give up or, worse, guess.

We had also made a second mistake. Our overview page, the one that explains authentication and shows examples, used to carry a hand-written list of every tool. As the API grew, that list drifted, so we removed it and pointed people at the interactive reference instead. For a human with a browser, fine. For a model, we had just deleted the only machine-readable catalogue we had.

What we changed

Render the whole catalogue into HTML. The overview page at /api-docs now fetches our OpenAPI document on the server, revalidated hourly, and renders every tool into the page: name, category, scope, description, and a parameter table with types, required flags, enum values and nested fields. Each tool is a collapsed details element, so the page stays readable for a person, but every word is in the server response. One fetch of one URL teaches a model the entire API.

Point at the raw spec too. The OpenAPI document is linked from the page header and from our llms.txt, because Claude Code, Cursor and ChatGPT will often take the spec directly if you give it to them.

Give the human a one-line handoff. The only thing the person has to do is paste. So the page says it plainly: "Building with Claude, ChatGPT or Cursor? Give it this page's URL." We put the same idea on the Developer API page as a copy-to-clipboard prompt that starts with "Read https://www.sellermate.ai/api-docs first".

Remove anything that makes the model hedge. We had a Beta badge on the page. When we asked ChatGPT how to use the API, it faithfully told the user "because the API is in beta, check the current parameter schema first". True, but it was a reason for a buyer to wait, and every model would repeat it. The API was stable enough; the badge went.

Fix the contradictions. Two of our pages described the behaviour of writes differently. A model reading one would write code that was wrong against the other. We made them agree. If your docs and your product page disagree, the model picks one at random and you find out from a support ticket.

Make the tool names the anchors. Every tool's section has the tool name as its id, so /api-docs#get_user_context lands on it. Our prompt library and articles link straight to the tool a prompt uses, and so can a model.

How we tested it

The same way a customer would. We asked ChatGPT, with web search on, how to pull campaign performance from SellerMate. It found the page, used the right header, called get_user_context first to list accounts, paginated correctly and named the metrics. It cited the documentation page twice. That is the bar now, and we re-run the test after every docs change.

We also learned something uncomfortable from search itself: a query for our product's name plus "API" returned a different company's CRM. Models with web search go where search goes. The fix for that is not in the docs; it is a GitHub repository, listings in the MCP directories, and articles like this one.

A checklist for your own API

Fetch your docs URL with curl. If the tools aren't in the response, a model can't see them.
Put the full catalogue, with parameters, in server-rendered HTML on one page.
Link the raw OpenAPI document from that page and from llms.txt.
Tell the human to paste the URL into their assistant. Say it on the page.
Remove hedges a model will repeat: beta badges, "may change", "contact us for access".
Make every page that describes behaviour agree with every other page.
Make tool names into anchors so prompts and articles can deep-link.
Ask ChatGPT and Claude how to use your API, with search on, and fix what they get wrong.
Then make your API findable where search looks: GitHub, directories, articles.

Why we bother

Because the people building on our API now are mostly not developers. They are account managers and brand owners with an AI assistant and an afternoon. For them, documentation that a model can read is the product. If the model can't read it, the API doesn't exist.

Read the docs · Developer API · Prompt library