API Idempotency Documentation Auditor

Audit public API documentation and turn API idempotency guidance into structured, cited findings.

Supply documentation URLs from payment, SaaS, or internal API providers. The Actor reports whether idempotency is documented, the header or key name, operation scope, retention, retry and error semantics, parameter-mismatch behavior, examples, caveats, provenance, and bounded per-URL errors.

It uses anonymous public pages. No vendor API key, browser, or language model is required.

What does the Actor do?

The Actor fetches each supplied public documentation page and extracts semantic content blocks such as paragraphs, lists, tables, and code samples.

It then classifies exact page excerpts into these topics:

• idempotency support;
• key or request-header name;
• operation and request scope;
• retention, expiry, and reuse timing;
• retry, timeout, and replay semantics;
• errors and conflicts;
• reuse with changed parameters or payload;
• examples;
• warnings and caveats.

Every citation keeps its topic, faithful contiguous quote from whitespace-normalized page text, nearest section heading, and final source URL. Quotes are bounded to 700 characters; truncated and sourceTextLength disclose clipping without adding an ellipsis to the quote. Classification uses the complete content block, not the clipped quote. Topics require local idempotency/header context rather than a mention elsewhere on the page. Missing evidence remains null, [], false, or not-found; the Actor does not invent an integration rule.

Who is this API idempotency audit for?

API integration engineers can build retry policies from cited vendor guidance rather than memory.

Platform and architecture teams can compare key names and retention windows across providers.

Technical writers can find gaps in their own public idempotency documentation.

Security and reliability reviewers can export evidence for implementation checklists.

Data and QA teams can schedule the same URL set and compare datasets when documentation changes.

Why use it?

Reading one page is easy. Repeating the review across many providers and preserving provenance is not.

The Actor provides:

• one consistent record per requested URL;
• explicit completed versus error status;
• exact evidence instead of unsupported summaries;
• normalized key names such as Idempotency-Key and PayPal-Request-Id;
• machine-readable output for spreadsheets, databases, and review pipelines;
• direct HTTP execution at a conservative 256 MB memory allocation;
• optional Apify Proxy configuration without an automatic residential-cost fallback.

It is a documentation auditor, not a guarantee that an upstream API behaves exactly as documented.

Data extracted

Field	Meaning
url	Requested documentation URL
finalUrl	URL after redirects
title	Page title
statusCode	Successful HTTP status
auditStatus	completed or error
idempotencySupport	documented or not-found
keyNames	Complete explicit header or parameter tokens supported by exported key citations, without clipped custom-header suffixes; the per-topic quote limit bounds coverage
operationScope	Cited operation/request-scope excerpt
retention	Cited retention or expiry excerpt
retrySemantics	Cited retry, timeout, or replay excerpt
errorSemantics	Cited error or conflict excerpt
parameterMismatchBehavior	Cited behavior for changed parameters or payload
examplesFound	Whether related example/code evidence was found
caveats	Cited warning and limitation excerpts
evidence	Topic, quote, section, and URL citations
evidenceCount	Number of exported citations
auditedAt	Audit timestamp
errorType	invalid-url, fetch, or content
errorMessage	Bounded diagnostic message

Nullable values mean that the page did not expose that fact in text the deterministic auditor could identify.

Getting started

1. Open the Actor input page.
2. Add one or more public API documentation URLs.
3. Keep maxUrls at or below the number you want processed.
4. Choose one to five evidence quotes per topic.
5. Leave retries at two unless a source is temporarily unstable.
6. Run the Actor.
7. Open the default dataset and select the overview view.
8. Inspect evidence before turning a finding into production retry logic.
9. Export JSON, CSV, Excel, or connect the dataset to your workflow.

The prefilled Stripe and PayPal URLs are real and can be run immediately.

Input parameters

startUrls

Required array of public HTTP(S) documentation pages.

Up to 100 entries are accepted. URLs are normalized (including fragment removal and default-port/hostname normalization) before deduplication and maxUrls selection. Fragment variants consume one request, record and successful audit event and do not crowd out another distinct URL.

Empty/non-array lists, more than 100 entries, non-object top-level input and invalid numeric settings fail the run. Individual malformed entries yield isolated invalid-url records without consuming the valid-URL limit.

URL credentials, localhost, private/reserved IP literals, .local, and .internal hosts are rejected. All DNS answers must be public; the checked IP is pinned for each connection and redirects are checked before connection. Error URLs omit credentials, queries and fragments.

maxUrls

Maximum unique URLs processed, from 1 to 100.

Default: 20.

evidenceQuotesPerTopic

Maximum citations retained for each topic, from 1 to 5.

Default: 2.

A larger value gives reviewers more context but creates larger dataset rows.

maxRetries

Transient HTTP retries per URL, from 0 to 3.

Default: 2.

Malformed URLs, unsupported content, and stable invalid responses are not turned into an unbounded retry loop.

proxyConfiguration

Optional standard Apify Proxy configuration.

Direct HTTP is used by default. Configure an HTTP(S) CONNECT proxy only when you are allowed to access the page and the documentation host rejects direct cloud requests. The proxy must support tunneling to a prevalidated public IP (for HTTP as well as HTTPS); proxies that require remote hostname resolution or do not support CONNECT return an isolated fetch error. HTTPS keeps original-host certificate verification and SNI. No proxy path bypasses destination checks.

The Actor never silently switches to residential proxy traffic.

Input example

{
  "startUrls": [
    { "url": "https://docs.stripe.com/api/idempotent_requests" },
    { "url": "https://developer.paypal.com/api/rest/reference/idempotency/" },
    { "url": "https://docs.adyen.com/development-resources/api-idempotency/" }
  ],
  "maxUrls": 3,
  "evidenceQuotesPerTopic": 2,
  "maxRetries": 2
}

This compares three payment API documentation contracts in one run.

Output example

A completed record has this shape (long quotes shortened here only for readability):

{
  "url": "https://docs.stripe.com/api/idempotent_requests",
  "finalUrl": "https://docs.stripe.com/api/idempotent_requests",
  "title": "Idempotent requests | Stripe API Reference",
  "statusCode": 200,
  "auditStatus": "completed",
  "idempotencySupport": "documented",
  "keyNames": ["Idempotency-Key"],
  "operationScope": "All POST requests accept idempotency keys.",
  "retention": "You can remove keys from the system automatically after they’re at least 24 hours old.",
  "retrySemantics": "Subsequent requests with the same key return the same result.",
  "errorSemantics": null,
  "parameterMismatchBehavior": "The idempotency layer compares incoming parameters to those of the original request and errors if they’re not the same.",
  "examplesFound": true,
  "caveats": [],
  "evidence": [
    {
      "topic": "key",
      "quote": "To perform an idempotent request, provide an additional Idempotency-Key element to the request options.",
      "section": "Idempotent requests",
      "sourceUrl": "https://docs.stripe.com/api/idempotent_requests"
    }
  ],
  "evidenceCount": 13,
  "auditedAt": "2025-01-15T12:00:00.000Z",
  "errorType": null,
  "errorMessage": null
}

Always use the live dataset quote, not this shortened documentation sample, as audit evidence.

Per-URL errors

One inaccessible URL does not erase useful results from other URLs.

A failed item is exported with:

• auditStatus: "error";
• a normalized errorType;
• a short errorMessage;
• empty findings and citations.

Failed URLs are not charged as successful documentation audits.

Invalid top-level input fails the run. Charge failures or an exhausted audit charge budget also stop the run before exporting unpaid useful output; earlier accepted records remain available.

How much does it cost to audit API idempotency documentation?

Pay-per-event billing includes a $0.010 start fee plus one audit event for each successfully audited URL.

Current per-audit prices are:

Plan	Price per successful audit
Free	$0.00056802
Bronze	$0.00049393
Silver	$0.00038527
Gold	$0.00029636
Platinum	$0.00029636
Diamond	$0.00029636

At Bronze pricing, one successful URL costs about $0.01049 including the start fee, 10 cost about $0.01494, and 100 cost about $0.05939. Error records do not add an audit charge.

Compute and optional proxy usage are handled by the Apify platform according to your plan. Check the run's charge details for the authoritative total.

Reliability and extraction limits

The Actor works best on server-rendered HTML documentation.

Each request has a 30-second timeout. Transient failures use bounded retries. Up to three URLs are fetched concurrently. Encoded and decompressed response streams are each limited to 8,000,000 bytes and cancelled when the bound is exceeded; oversized bodies are not fully buffered. Redirects are limited to ten hops.

A page can return not-found when:

• it genuinely does not document idempotency;
• relevant guidance is loaded only after complex browser interaction;
• wording is too unusual for deterministic topic matching;
• the URL is an index page while the details live on linked pages.

The Actor audits only supplied pages. It does not crawl every link in an API portal.

PDF, JSON, video, and authenticated/private documentation are outside the current input contract.

Evidence interpretation tips

Treat every summary field as a convenient pointer to its corresponding citation.

Review all evidence when:

• the same provider has multiple API generations;
• one key has different retention by endpoint;
• errors differ for concurrent and sequential requests;
• regional endpoints have different behavior;
• a page mixes client-library behavior with raw HTTP behavior.

not-found means “not found on this fetched page,” not “the API cannot be idempotent.”

A provider may support naturally idempotent HTTP methods without an explicit key. The Actor reports what the page says.

Automation workflows

Integration design review

Audit candidate providers, filter completed rows, and turn citations into a retry-policy checklist.

Documentation regression monitoring

Schedule the same input and compare retained datasets by URL and topic. A missing quote can prompt human review.

Internal API governance

Run against anonymous public documentation pages owned by your organization and flag missing retention or parameter-mismatch guidance.

Vendor migration

Compare old and new provider pages before replacing a payment, messaging, or provisioning integration.

Data warehouse export

Send dataset records to BigQuery, Snowflake, PostgreSQL, or a webhook using standard Apify integrations.

Run through the Apify API

Replace YOUR_TOKEN with an Apify API token.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~api-idempotency-documentation-auditor/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":[{"url":"https://docs.stripe.com/api/idempotent_requests"}],"maxUrls":1}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/api-idempotency-documentation-auditor').call({
  startUrls: [{ url: 'https://docs.stripe.com/api/idempotent_requests' }],
  maxUrls: 1,
  evidenceQuotesPerTopic: 3,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("automation-lab/api-idempotency-documentation-auditor").call(run_input={
    "startUrls": [{"url": "https://docs.stripe.com/api/idempotent_requests"}],
    "maxUrls": 1,
    "evidenceQuotesPerTopic": 3,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use with MCP and AI agents

Claude Code

Add the Actor to Claude Code through Apify MCP:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/api-idempotency-documentation-auditor"

Claude Desktop, Cursor, and VS Code

Claude Desktop, Cursor, and VS Code clients can use this MCP server configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/api-idempotency-documentation-auditor"
    }
  }
}

Example prompts

Useful MCP prompts include:

• “Audit these three payment API documentation URLs and compare key retention.”
• “Show only completed audits whose parameter mismatch behavior was found.”
• “Create an implementation checklist and cite every source quote.”
• “Explain which URLs failed without treating them as unsupported APIs.”

Keep a human reviewer in the loop before an agent changes production retry logic.

Diagnostics and privacy

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed; reports are retained for 30 days. Logs and per-URL errors exclude URL credentials, queries and fragments. Successful output retains requested/final source URLs for provenance, so supply only public documentation URLs without private path data.

idempotencySupport: "documented" means the topic is discussed, including explicit non-support or limitations. It is not an affirmative guarantee of API behavior; read the cited wording.

Storage and support

Fetched HTML is processed in memory, not saved as a raw capture. Results and input remain in your Apify run storage under your account retention settings; delete datasets and key-value stores in Apify Console when no longer needed. Run logs follow platform retention. Optional proxy providers receive the public destination and traffic; enable a proxy only deliberately. No AI service receives inputs or page content.

For help, use the Actor's Apify Store Issues tab and include the run link and a public documentation URL. Do not include secrets. This is an independent Automation Lab tool, not affiliated with or endorsed by the documentation providers named in examples.

Legality

Process only public documentation you are permitted to access.

Respect website terms, robots guidance, rate limits, copyright, and applicable law. Keep evidence excerpts limited to the review purpose and link back to the source.

Do not use the Actor to bypass authentication, access private portals, or probe internal network addresses.

Documentation can be incomplete or outdated. Validate high-impact implementation decisions against the provider's current official contract and test environment.

Troubleshooting

Why did I get not-found?

Open the final URL and confirm the supplied page itself contains explicit idempotency text. Increase evidenceQuotesPerTopic only to retain more matches; it does not make the matcher broader.

If the guidance is on another linked page, add that page to startUrls.

Why did I get a fetch error?

Inspect errorMessage and Actor logs. Confirm the page is anonymous and public. A 404 normally means the documentation URL changed. A 429 or 5xx may succeed on a later scheduled run.

Use a proxy only when permitted and necessary.

Why did I get a content error?

The host may have returned a challenge, unsupported media type, or response larger than 8 MB. Supply a direct HTML documentation URL.

Why is a field null while citations exist for other topics?

The page documented some parts of the contract but the Actor did not find a qualifying excerpt for that field. This is useful gap evidence, not a parser crash.

Are errors charged?

The one-time start event applies to the run. The per-audit event applies only to successfully completed URL audits, not error records.

FAQ

Does this test the API itself?

No. It audits documentation text. It sends no requests to the documented business API.

Does it use AI?

No. Extraction and classification are deterministic, which keeps citations reproducible and runtime inexpensive.

Can it audit OpenAPI files?

Not in the current version. Supply rendered public HTML documentation pages.

Can it crawl an entire documentation portal?

No. The Actor intentionally audits the exact URLs supplied so scope and cost remain predictable.

Can I schedule recurring audits?

Yes. Use an Apify schedule with the same input, then compare datasets or send records to your monitoring system.

What language works best?

The current topic patterns target English documentation. Other languages can return partial or not-found results.

How many URLs can one run process?

Up to 100 unique URLs.

Related Automation Lab Actors

For adjacent public-page workflows, consider:

• Webpage Text Extractor when you need general page text rather than idempotency findings.
• Webpage Structured Data Monitor when you need JSON-LD, Open Graph, microdata, or RDFa change detection.
• Robots & Sitemap Analyzer when you need crawl-policy and sitemap inspection before a larger documentation workflow.

These Actors solve different jobs and are not required by this auditor.