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, exact quote, nearest section heading, and final source URL. 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	Explicit header or parameter names found
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. Duplicate string URLs are processed once. Fragments are removed before fetching.

Localhost, private IP literals, .local, and .internal hosts are rejected.

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 a proxy only when you are allowed to access the page and the documentation host rejects direct cloud requests.

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.

The whole run fails only when the top-level input contract is invalid, such as an empty URL list or an out-of-range numeric setting.

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, and each response is limited to 8 MB.

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.

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.