# API Idempotency Documentation Auditor (`automation-lab/api-idempotency-documentation-auditor`) Actor

Turn public API documentation into implementation-ready idempotency findings with cited key names, retry rules, scope, retention, mismatch behavior, examples, and per-URL errors.

- **URL**: https://apify.com/automation-lab/api-idempotency-documentation-auditor.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.30 / 1,000 audit extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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

```json
{
  "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):

```json
{
  "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

```bash
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

```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

```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:

```bash
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:

```json
{
  "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](https://apify.com/automation-lab/webpage-text-extractor) when you need general page text rather than idempotency findings.
- [Webpage Structured Data Monitor](https://apify.com/automation-lab/webpage-structured-data-monitor) when you need JSON-LD, Open Graph, microdata, or RDFa change detection.
- [Robots & Sitemap Analyzer](https://apify.com/automation-lab/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.

# Actor input Schema

## `startUrls` (type: `array`):

Public HTTP(S) API documentation pages to audit. Each URL produces either one completed audit or one error record.

## `maxUrls` (type: `integer`):

Maximum number of unique documentation URLs processed in this run.

## `evidenceQuotesPerTopic` (type: `integer`):

Maximum cited page excerpts retained for each audit topic.

## `maxRetries` (type: `integer`):

Retries for transient network, rate-limit, and server failures. Invalid or permanently rejected pages are not retried blindly.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy settings for public documentation sites that reject direct cloud traffic.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://docs.stripe.com/api/idempotent_requests"
    },
    {
      "url": "https://developer.paypal.com/api/rest/reference/idempotency/"
    }
  ],
  "maxUrls": 20,
  "evidenceQuotesPerTopic": 2,
  "maxRetries": 2
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset items shown with the idempotency audit overview view.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://docs.stripe.com/api/idempotent_requests"
        },
        {
            "url": "https://developer.paypal.com/api/rest/reference/idempotency/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/api-idempotency-documentation-auditor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "startUrls": [
        { "url": "https://docs.stripe.com/api/idempotent_requests" },
        { "url": "https://developer.paypal.com/api/rest/reference/idempotency/" },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/api-idempotency-documentation-auditor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://docs.stripe.com/api/idempotent_requests"
    },
    {
      "url": "https://developer.paypal.com/api/rest/reference/idempotency/"
    }
  ]
}' |
apify call automation-lab/api-idempotency-documentation-auditor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/api-idempotency-documentation-auditor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/HfSzpsW16M2n2J6pn/builds/RNQs5uVAYBV554xQM/openapi.json