- Home
- Skills
- APIs & Backend
- API friction walkthrough
API friction walkthrough
Audit API docs and specs from a first-time developer's perspective to find breaking friction and contradictions.
Free
Works with the AI Agents you already use
API friction walkthrough
Example session with this skill installed
Perform an API friction walkthrough for the attached pet-breed.yaml and README.md.
- Read your context and instructions
- Compiled the api friction walkthrough
API friction walkthrough: breeds, photos and votes
The docs and the OpenAPI spec disagree in several places, and an integrator following either use case would hit the first problem on the first call. 10 findings. The first four break copy-paste code or generated clients before anything else works: the value for random order, a required upload field missing from the example, whether an API key is needed, and the breed ID type.
What I read: the Getting Started, Authorization, Errors and limits, Breeds, Images, Image Uploads, Pagination and Votes & Favourites pages, the API Reference, and the OpenAPI spec. The site looks published. I treated the spec as in scope because the docs link to it. I left out GitHub, Discord, the demo apps and the advanced guides, because the use cases below don't need them.
Two limits on this walkthrough
- My fetch tool summarizes long pages. Code samples and the key sentences are quoted word for word; the rest of the prose I saw as summaries.
- I didn't call the live API. There was no key, and the review only covers the docs.
Purpose
This API lets a developer show animal breed information and photos in their app, and let their users vote on and favourite those photos. Paid plans add photo analysis.
The landing page makes this clear. One thing is not: the breed count sits on the front page, but the full breed dataset and the photo analysis need a paid plan. A Free user won't know what they actually get until they call GET /accounts/features.
Use cases
- Breed browser: search breeds by name, open one breed's details, then show a page of photos of that breed.
Voting app: show a random photo. A signed-in user votes it up or down, can favourite it, later sees their own favourites and can remove one.
Findings
1. The docs and the spec disagree on the value for random order
Where: the Images page lists order as ASC, DESC, RAND. The spec enum for /images/search, /breeds and /votes is ASC, DESC, RANDOM. The Pagination page says only ASC or DESC.
Why it matters: blocks use case 2 at its first call. A developer who copies RAND from the docs, or a client generated from the spec, will get a 400 or the wrong order, depending on which source is right. Nothing in scope says which is right.
2. The copy-paste upload example leaves out a field the spec requires
Where: Image Uploads, async upload curl. The spec's POST /images/upload lists type (base64 or FILE) as required. The docs' field table lists type without saying it's required, and the curl sample doesn't send it.
Why it matters: the first photo a developer uploads may fail on the docs' own example. It sits beside use case 2 (user-contributed photos).
3. Three places disagree on whether an API key is needed
Where: Authorization says to send the key "with every request". The Images page says limit is "1–100 with an API key", which suggests calls without a key work with a different cap. The spec puts no security on GET /images/search, GET /votes or GET /votes/{vote_id}, while it does on /favourites.
Why it matters: use cases 1 and 2. A client generated from the spec won't send the key on those calls. Without a key it would get a 403, or possibly someone else's votes. A developer can't tell which.
4. The breed ID type is contradicted three ways
Where: the Breeds page says "Breed IDs are numeric". The spec has /breeds/{id} and ProBreedDto.id as string. The sync upload response example shows "id": "1".
Why it matters: use case 1. The breed ID returned by search is what gets passed to breed_ids for photos. A strongly typed client will choose one type and break on the other.
5. Votes: the allowed values and how to reverse a vote are missing
Where: the Votes & Favourites page shows only "value": 1 and says "post a new vote with the opposite value" without saying what that value is. The spec says value is a number described as "1 for upvote, -1 for downvote", with no enum. The docs also say votes "cannot be deleted".
Why it matters: use case 2. The developer has to guess -1 (or 0?). Reversals add a new record rather than replacing the old one, so the app has to work out each user's current vote itself. Nothing explains how to do that: latest wins? Sum them?
6. The docs don't mention sub_id for votes
Where: the docs explain sub_id only for favourites. The spec has sub_id on CreateVoteDto, VoteDto and as a filter on GET /votes.
Why it matters: use case 2 needs to track votes per user. A developer reading only the docs would think votes can't be tied to their users.
7. Free plan limit is low, with no headers to manage it
Where: Authorization says "Free plans are limited to 10 requests per minute." Errors and limits says it "doesn't document any rate-limit response headers". The Getting Started page gives no number at all.
Why it matters: use case 2. In a voting app each vote is a request, so a handful of active users exceeds 10 per minute. The only signal is a 429 after the fact.
8. Image search returns one image by default, and the docs don't say so
Where: the spec sets limit default to 1 on /images/search. The Images page gives the range (1–100) but not the default.
Why it matters: use case 1. "Show a page of photos of this breed" returns a single photo unless the developer already knows to set limit.
9. The upload status flow is part guesswork
- Where: Image Uploads.
- It says the status is "likely
to_be_reviewed" while processing. - Async returns
pending/approvedcounts, and sync returnsreview_status. Neither matches the status endpoint'sstatusfield. - The docs' status table leaves out
does_not_contain_species, which the spec includes. - Both
cleanandlabelledare described as "ready to use", with no word on which is final. - The spec says to poll
links.status, butImageDtohas nolinksfield. - Allowed file types aren't stated on the upload page. The 50 MB limit is only on Errors and limits.
- It says the status is "likely
- Why it matters: anyone polling for an approved upload has to guess when to stop.
10. No response examples for votes and favourites
Where: none of the votes and favourites curl examples on the page show a response. The spec gives FavouriteDto.id as a number but the DELETE /favourites/{id} path parameter as a string.
Why it matters: use case 2. To remove a favourite you need the ID from the create response, and the docs never show it. What happens when the same image is favourited twice (a 409 or a duplicate?) isn't covered either.
The first four are worth fixing first: they break copy-paste or generated clients before anything else happens.
Connects securely to your tools. The creator never sees your data.
About this skill
API documentation often hides traps that only appear when a developer actually starts coding. This skill audits your API surface from the perspective of a first-time integrator to identify where they will get confused, guess wrong, or fail. It focuses on contradictions between prose, specs, and code samples to ensure your developer experience is actually functional.
What it does
- Purpose validation defines the API's value proposition from an outside-in perspective to ensure the core utility is clear.
- Use case mapping generates 1-2 concrete, multi-step scenarios that a real integrator would attempt.
- Path testing follows the developer journey to find where names, descriptions, or examples deviate from the actual contract.
- Friction identification flags issues, including where copy-pasteable examples fail, errors provide no direction, or schemas hide essential data shapes.
How it works
- Provide the docs URL, spec file, or draft documentation you want reviewed.
- The agent identifies the API purpose and proposes 1-2 anchoring use cases.
- It performs a walkthrough of those cases using only the provided surface.
- It generates a report detailing what broke, where it happened, and which use case is impacted.
Frameworks & tools
Works with OpenAPI / Swagger specs, Markdown documentation, hosted doc portals, and raw code examples.
Why this beats prompting it yourself
Generic prompts often use "insider knowledge" from within your repository. This skill strictly enforces the "outside-in" constraint, ensuring you see exactly what a new customer sees without the bias of knowing how the backend works.
Use cases
- Audit a new API version before it goes live to public developers.
- Compare OpenAPI specs against prose tutorials to find naming drift.
- Validate that getting-started guides actually result in a successful integration.
- Check if error messages provide enough context to unblock a failing dev.
Known limitations
Does not test live endpoints or perform network calls. Requires the user to provide the full text or files of the documentation surface for review. Generates 1-2 use cases even when the API supports many.
Requires user-provided documentation or spec files. Does not perform live API requests or integration testing. Won't use internal repo context unless explicitly provided in the scope.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 14 days ago
- Free with an Agensi account
Permissions
Browser permissions are required to review provided URLs; read files are required to review the provided files on your machine.