# Citation Remediation Payload Generator (`bono718/citation-remediation-payload-generator`) Actor

Generate deterministic HTML and WebPage JSON-LD remediation instructions from supplied AI citation evidence and page snapshots. Includes snapshot checks and acceptance tests. No live page edits or citation uplift guarantee.

- **URL**: https://apify.com/bono718/citation-remediation-payload-generator.md
- **Developed by:** [Alessandro Bonometti](https://apify.com/bono718) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 remediation payloads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Citation Remediation Payload Generator

Turn supplied AI citation evidence and HTML snapshots into deterministic JSON instructions for a downstream HTML consumer.

This Actor helps prepare conservative changes when supplied evidence cites a competitor page and omits your target page. It uses facts already present in your target snapshot. It does not predict or guarantee that an AI system will cite your page.

### What it does

- Processes one target page, one cited competitor page and one query per run.
- Checks the citation gap in the URLs supplied by the caller.
- Proposes a query heading and grounded excerpts when applicable.
- Proposes minimal WebPage JSON-LD when missing.
- Returns snapshot hashes, change preconditions and typed acceptance tests.

### Input example

```json
{
  "targetUrl": "https://example.com/product",
  "competitorUrl": "https://competitor.example/product",
  "query": "Does Acme export CSV?",
  "evidence": {
    "answer": "The competitor offers CSV exports.",
    "citedUrls": ["https://competitor.example/product"]
  },
  "targetHtml": "<!doctype html><html><body><h1>Acme</h1><p>Acme exports reports in CSV format.</p></body></html>",
  "competitorHtml": "<html><body><h1>CSV exports</h1></body></html>",
  "facts": [{
    "text": "Acme exports reports in CSV format.",
    "sourceUrl": "https://example.com/product"
  }]
}
```

Supply relevant, truthful facts and current snapshots. Unknown input fields are rejected. Citation evidence is caller-supplied and is not independently authenticated. Competitor HTML is used only for heading comparison.

### Output

The Actor writes a structured JSON result to the run's default dataset. It includes `schemaVersion`, `inputHash`, `status`, provenance and snapshot hashes, `diagnosis`, `changes`, `acceptanceTests` and `warnings`. Heading comparison may also be present.

The example above produces a `ready` payload with an HTML section, minimal WebPage JSON-LD and acceptance tests. Other inputs may produce fewer changes, `no_gap` or `no_action`.

Supported changes are `append_html` and `append_json_ld`. Tests are typed instructions: `selector_count`, `text_contains` and `json_ld_webpage_url`. They are not arbitrary executable code.

### Applying a payload

The Actor returns instructions; it does not edit your website. Before applying any change, your consumer must verify all snapshot hashes and selector preconditions against the original snapshot. Track applied change IDs, support rollback and refuse already-applied changes. Use an appropriate CMS adapter for production writes.

### Limitations

The Actor does not fetch live pages, render JavaScript, collect citation evidence, perform semantic gap analysis, predict rankings, discover internal links, generate FAQ schema, write to a CMS or process bulk jobs. Excerpt matching verifies occurrence rather than factual truth or relevance. Minimal WebPage JSON-LD does not establish Google rich-results eligibility. A repeated query heading can suppress a content change even if existing content is inadequate.

### Pricing

- **Remediation payload:** USD 0.02 for one result with status `ready`, regardless of the number of proposed changes.
- **Actor start:** USD 0.00005 per run with the supported memory allocation of 256–512 MB.
- **Platform usage:** included in the event prices.

A run producing one `ready` payload costs USD 0.02005. Results with status `no_gap` or `no_action` do not incur the remediation-payload charge; the startup charge may still apply. Invalid or failed runs may also incur a startup charge. There is no additional automatic dataset-item fee.

Set a maximum cost per run to control spending. If the remaining budget cannot cover a ready payload, it will not be delivered.

# Actor input Schema

## `targetUrl` (type: `string`):

HTTP(S) URL matching the supplied target snapshot.

## `competitorUrl` (type: `string`):

Exact competitor page cited in the evidence.

## `query` (type: `string`):

Question to expose in a target heading; 3–500 characters.

## `evidence` (type: `object`):

Object with answer (string) and citedUrls (array of HTTP(S) URLs). Caller must attest accuracy.

## `targetHtml` (type: `string`):

Supplied HTML; max 1,000,000 characters. No network retrieval.

## `competitorHtml` (type: `string`):

Supplied HTML; max 1,000,000 characters.

## `facts` (type: `array`):

1–10 objects with text (exact visible target excerpt, 5–500 chars) and sourceUrl (target URL). Choose excerpts that answer the query.

## Actor input object example

```json
{
  "targetUrl": "https://example.com/product",
  "competitorUrl": "https://competitor.example/product",
  "query": "Does Acme export CSV?",
  "evidence": {
    "answer": "The competitor offers CSV exports.",
    "citedUrls": [
      "https://competitor.example/product"
    ]
  },
  "targetHtml": "<!doctype html><html><body><h1>Acme</h1><p>Acme exports reports in CSV format.</p></body></html>",
  "competitorHtml": "<html><body><h1>CSV exports</h1></body></html>",
  "facts": [
    {
      "text": "Acme exports reports in CSV format.",
      "sourceUrl": "https://example.com/product"
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Structured result with status, proposed changes, snapshot preconditions, acceptance tests and warnings.

# 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 = {
    "targetUrl": "https://example.com/product",
    "competitorUrl": "https://competitor.example/product",
    "query": "Does Acme export CSV?",
    "evidence": {
        "answer": "The competitor offers CSV exports.",
        "citedUrls": [
            "https://competitor.example/product"
        ]
    },
    "targetHtml": "<!doctype html><html><body><h1>Acme</h1><p>Acme exports reports in CSV format.</p></body></html>",
    "competitorHtml": "<html><body><h1>CSV exports</h1></body></html>",
    "facts": [
        {
            "text": "Acme exports reports in CSV format.",
            "sourceUrl": "https://example.com/product"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("bono718/citation-remediation-payload-generator").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 = {
    "targetUrl": "https://example.com/product",
    "competitorUrl": "https://competitor.example/product",
    "query": "Does Acme export CSV?",
    "evidence": {
        "answer": "The competitor offers CSV exports.",
        "citedUrls": ["https://competitor.example/product"],
    },
    "targetHtml": "<!doctype html><html><body><h1>Acme</h1><p>Acme exports reports in CSV format.</p></body></html>",
    "competitorHtml": "<html><body><h1>CSV exports</h1></body></html>",
    "facts": [{
            "text": "Acme exports reports in CSV format.",
            "sourceUrl": "https://example.com/product",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("bono718/citation-remediation-payload-generator").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 '{
  "targetUrl": "https://example.com/product",
  "competitorUrl": "https://competitor.example/product",
  "query": "Does Acme export CSV?",
  "evidence": {
    "answer": "The competitor offers CSV exports.",
    "citedUrls": [
      "https://competitor.example/product"
    ]
  },
  "targetHtml": "<!doctype html><html><body><h1>Acme</h1><p>Acme exports reports in CSV format.</p></body></html>",
  "competitorHtml": "<html><body><h1>CSV exports</h1></body></html>",
  "facts": [
    {
      "text": "Acme exports reports in CSV format.",
      "sourceUrl": "https://example.com/product"
    }
  ]
}' |
apify call bono718/citation-remediation-payload-generator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bono718/citation-remediation-payload-generator"
        }
    }
}
```

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/Ex2lIxIRmW5LggKfM/builds/LlTUWCxGhSkadfiLH/openapi.json