There's a new test for API documentation, and most APIs fail it.
Take your docs, paste the link into Claude or ChatGPT, and ask for a working integration: "Read this and write me the code to sell airtime from my app." Then run what comes back. If it works first time, your documentation is good. Not marketing-page good. Actually good, in the only sense that matters: a reader with no context, no tribal knowledge and no ability to phone your support line understood it completely.
We run this test on our own docs, because we discovered something that changed how we write them: an AI reading your documentation is the world's most honest junior developer. It doesn't skim. It doesn't fill gaps with assumptions from the last three APIs it integrated. It reads exactly what you wrote, and if what you wrote is ambiguous, incomplete or quietly contradicts itself, the code comes back wrong in ways that show you precisely where your docs lied. Every gap an AI falls into is a gap a human developer was falling into too. The human just never told you. They swore at the screen, guessed, and shipped the guess.
So we treat "an AI can integrate SIMcloud unassisted" as a hard requirement, the way other teams treat uptime. Here's what that forces on the documentation, and why you, a human with a deadline, are the real beneficiary.
What breaks when a machine reads your docs
Ask an AI to integrate a few dozen APIs and you start noticing that documentation almost always fails in the same ordinary ways. Authentication is explained on three different pages that don't quite agree. Error responses aren't documented at all, so the first 400 you hit in testing is a mystery you solve by guessing. Examples cover only the happy path, as if payments never bounce and networks never time out. And somewhere, the one rule that actually matters in production is sitting in a support article nobody linked from the reference.
None of these are machine problems. They are reader problems that machines finally made measurable. Fixing them for the AI fixed them for everyone, which is why our docs read the way they do: one page per product, auth stated once and identically everywhere, every request paired with its real response, and every error you can trigger listed next to the call that triggers it. Boring, predictable, symmetrical. Documentation should be the least surprising thing about your stack.
Built for real money
Clear docs are table stakes. What actually earns a developer's trust is when the API's design shows that the people who built it have lost money the same ways you're about to. A few examples of what that looks like in ours.
Orders are asynchronous, and we say so up front. When you submit an airtime recharge or an electricity purchase, you get back an order identifier immediately, and the final result arrives when the mobile network or vending system confirms it. Plenty of APIs pretend this isn't true and make you discover the timing the hard way, in production, at month end. Ours hands you the order ID, tells you to persist it, and gives you a status call to poll. That order ID is also your audit trail: months later, it still resolves to what was ordered, for which number or meter, and what happened.
Duplicate protection is built in, because retries happen. Networks flap. Cron jobs fire twice. A stressed developer clicks run again. If our API sees an order for the same number and the same amount within five minutes of the last one, it refuses with an honest HTTP 409 and a message saying exactly why, rather than cheerfully billing you twice. It is a small rule. It has saved customers from a very specific 2am phone call more times than we can count, and it's in the docs where you'll read it before you need it, not in an apology email after.
The catalogue is live, because the products are. Data bundles and voucher denominations change without asking your codebase's permission. So there is no PDF price list to hardcode and quietly rot; you query the catalogue, and what comes back is orderable right now. The integrations that break every quarter are, almost without exception, the ones built on a stale list somebody pasted into a config file in 2021.
Electricity purchases are treated as the irreversible things they are. A prepaid electricity token, once generated for a meter, cannot be un-generated. So the docs put a meter validation call in front of the purchase, tell you to use it, and say plainly that what follows is the point of no return. Check the meter, get back the actual provider by name, then commit. An API that lets you stumble backwards into an irreversible purchase is not simple. It is a lawsuit with good ergonomics.
Here is that whole flow, verbatim from the docs. Validate:
GET /api/electricity.php?meter_number=01234567890
{
"status": "success",
"message": "We support this meter.",
"supported": true,
"provider": "City of Ekurhuleni IMMS"
}Order, and notice the response tells you the fee to the cent, split out from the electricity itself:
POST /api/electricity.php
{
"meter_number": "01234567890",
"amount": 150.00,
"client_reference": "INV-10045",
"recipient": "0821234567"
}
{
"status": "success",
"order_id": 415,
"amount": 150,
"electricity_amount": 145.63,
"fee": 4.37,
"billing_status": "pending"
}Then poll GET ?order_id=415 until the municipality answers, and the final response contains the token and the units, ready to hand to your customer:
{
"status": "success",
"recharge_pin_information": [
{ "description": "PURCHASE", "pin": "0092 0215 1214 3650 1304", "units": "13.70" }
]
}Three calls, no mysteries, and the failure modes (502 when the municipality is down, 503 when the service is) are documented next to the happy path, because in the real world municipalities are sometimes down.
None of this is revolutionary computer science. It is the accumulated scar tissue of running prepaid infrastructure since 2003, written down where you can benefit from it before your own scars form.
Then we went one step further than docs
If documentation an AI can read is the new baseline, there's an obvious next move: skip the reading-comprehension step entirely and hand the AI the tools themselves.
That's what MCP is, the Model Context Protocol, and SIMcloud runs on it. Connect the SIMcloud MCP server at simcloud.co.za/api/mcp.php to Claude, ChatGPT or Codex and the assistant doesn't just understand our API. It can check your wallet balance, look up which network a number is on, and place a recharge, as tools it calls directly, with you approving what matters. And it does this properly: each user signs in to their own SIMcloud account over OAuth, with standard discovery endpoints and dynamic client registration, so tool calls run against your wallet and your permissions. Nobody shares a master token, because "just paste the company API key into the chatbot" is not a security model, it's an incident report with a delay on it.
To our knowledge we were the first airtime provider in South Africa you could operate this way, and it wasn't a stunt. It was the logical endpoint of the same principle: an interface that is genuinely clear should be usable by anyone, or anything, that can read. There's even a machine-readable contract at /api/openapi.yaml for tooling and generated clients, and the AI integration guide includes a copy-paste prompt you can hand to your assistant as-is.
For most developers, the practical payoff is quieter than the demo. It means your AI coding assistant, the one already sitting in your editor, integrates SIMcloud correctly on the first attempt, because both halves of the conversation, the docs and the tools, were built to be understood. Our guide on choosing software AI agents can use goes deeper on that idea, including where a human approval gate belongs when the agent can spend real money.
What "minutes" honestly means
Every API in the world claims you can integrate it in minutes, so let us be precise about the claim, because precision is the whole brand here.
Minutes gets you to your first successful call: account, API token, wallet loaded, a real recharge landing on your own phone. The PHP, Node.js and Python guides each get you there in one sitting, and honestly, so does pasting the docs into your AI assistant and asking.
Production takes longer, and it should. Persisting order IDs properly, deciding your retry policy, wiring the status polling into your reconciliation, handling the day a recharge fails after your customer already paid you: that's real engineering, it's yours to own, and the docs treat you like the professional who has to own it. What we promise is narrower and more valuable than "minutes": no time lost to us. Every hour you spend integrating SIMcloud goes into your system, not into decoding ours.
And because the closing argument of an article like this should be executable, here is the entire integration surface of your first airtime order, verbatim from the docs:
POST /api/airtime.php
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
{
"msisdn": "0821234567",
"network": "p-mtn",
"amount": 10.00,
"reference": "Airtime for John"
}
{
"status": "success",
"message": "Airtime order queued successfully",
"request_id": 1527245,
"queue_status": "queued"
}Four fields in, a request_id out, and one GET to poll it from queued through pending to delivered. Amounts run from R2 to R999, the token comes from your portal, and that is genuinely all of it.
That's the test, and it's yours to run right now: open the API documentation, hand it to the AI of your choice, and ask for the integration. If what comes back doesn't work, we want to hear about it, because by our own standard, that's a bug in the docs.
We're fairly confident you'll be sending airtime before your coffee goes cold.
Create a free account, generate your API token, and make your first call to a list of one: your own number. No monthly fees, and you can load as little into the wallet as you like while you test.