Quickstart

Your first check, step by step.

Docs menu
  1. Create an account and copy your test key. It is shown once.
  2. Send one request. Test mode returns sample answers and costs nothing.
  3. Swap in your live key when you are ready.

The samples below are in curl, JavaScript and Python. Each one runs as written.

  1. Get a test key

    Open the console, finish the short account form and choose Keys. Make a key in test mode. It starts with pp_test_. We show it once and keep only a fingerprint of it, so copy it now.

    Keep it in an environment variable so it never sits in your code:

    Mac, Linux, Git Bash

    export PRESSPROVE_API_KEY=pp_test_...

    PowerShell

    $env:PRESSPROVE_API_KEY = "pp_test_..."
  2. Send a check

    The script below makes a check of one sample page, waits for it and prints the answer. A test check finishes about two seconds after it is queued.

    curl

    # 1. Create the check. The answer is 202 with the check queued.
    ID=$(curl -s -X POST https://pressprove.com/api/v1/checks \
      -H "Authorization: Bearer $PRESSPROVE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"pages":["https://news.example.org/2026/11/live-link-roastery"],"client_domain":"example.com"}' \
      | grep -o '"id": *"chk_[0-9A-Za-z]*"' | head -1 | cut -d'"' -f4)
    echo "check $ID"
    
    # 2. A test check completes about two seconds later. Read it.
    sleep 5
    curl -s https://pressprove.com/api/v1/checks/$ID \
      -H "Authorization: Bearer $PRESSPROVE_API_KEY"

    JavaScript

    const base = "https://pressprove.com/api/v1";
    const headers = {
      Authorization: `Bearer ${process.env.PRESSPROVE_API_KEY}`,
      "Content-Type": "application/json",
    };
    
    // 1. Create the check. The answer is 202 with the check queued.
    const created = await fetch(`${base}/checks`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        "pages": [
          "https://news.example.org/2026/11/live-link-roastery"
        ],
        "client_domain": "example.com"
      }),
    });
    const check = await created.json();
    if (!created.ok) throw new Error(JSON.stringify(check));
    
    // 2. Poll until it is no longer queued or running.
    let current = check;
    while (current.status === "queued" || current.status === "running") {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      const response = await fetch(`${base}/checks/${check.id}`, { headers });
      current = await response.json();
    }
    console.log(JSON.stringify(current, null, 2));

    Python

    import json
    import os
    import time
    
    import requests  # pip install requests
    
    BASE = "https://pressprove.com/api/v1"
    HEADERS = {"Authorization": "Bearer " + os.environ["PRESSPROVE_API_KEY"]}
    
    # 1. Create the check. The answer is 202 with the check queued.
    created = requests.post(
        BASE + "/checks",
        headers=HEADERS,
        json={
            "pages": [
                "https://news.example.org/2026/11/live-link-roastery",
            ],
            "client_domain": "example.com",
        },
        timeout=30,
    )
    check = created.json()
    if not created.ok:
        raise SystemExit(json.dumps(check))
    
    # 2. Poll until it is no longer queued or running.
    while check["status"] in ("queued", "running"):
        time.sleep(2)
        check = requests.get(BASE + "/checks/" + check["id"], headers=HEADERS, timeout=30).json()
    print(json.dumps(check, indent=2))
  3. Read the answer

    This is the answer you get. The id and the times differ on each run; the rest is the same. In test mode it is decided by the words in the page address: this address contains live-link.

    JSON

    {
      "id": "chk_0Lr8KpQ2aB3xYw5nT7pUeC",
      "object": "check",
      "livemode": false,
      "status": "completed",
      "mode": "link_check",
      "kind": "check",
      "source": "api",
      "monitor_id": null,
      "project_id": null,
      "client_domain": "example.com",
      "page_count": 1,
      "pages": [
        {
          "object": "page_result",
          "position": 0,
          "url": "https://news.example.org/2026/11/live-link-roastery",
          "verdict": "LINK_LIVE",
          "fetched_at": "2026-11-02T09:30:00Z",
          "reused": false,
          "final_url": {
            "known": true,
            "value": "https://news.example.org/2026/11/live-link-roastery"
          },
          "http_status": {
            "known": true,
            "value": 200
          },
          "registrable_domain": {
            "known": true,
            "value": "news.example.org"
          },
          "text": {
            "found": {
              "known": false,
              "reason": "text_not_supplied_link_check_mode"
            },
            "matched_phrase": {
              "known": false,
              "reason": "text_not_supplied_link_check_mode"
            },
            "match_zone": {
              "known": false,
              "reason": "text_not_supplied_link_check_mode"
            }
          },
          "links": {
            "present": {
              "known": true,
              "value": true
            },
            "count": {
              "known": true,
              "value": 1
            },
            "rel_summary": {
              "known": true,
              "value": "sponsored nofollow"
            },
            "items": [
              {
                "href": "https://example.com/",
                "rel_raw": "sponsored nofollow",
                "rel_tokens": [
                  "sponsored",
                  "nofollow"
                ],
                "anchor_text": "Sample anchor",
                "zone": "body"
              }
            ],
            "items_truncated": false
          },
          "disclosure": {
            "present": {
              "known": true,
              "value": true
            },
            "explicit": {
              "known": true,
              "value": true
            },
            "prominence": {
              "known": true,
              "value": "headline_area"
            },
            "matches": [
              {
                "term": "sponsored",
                "matched_text": "Sponsored",
                "zone": "headline_area",
                "strength": "explicit"
              }
            ]
          },
          "noindex": {
            "known": true,
            "value": false
          },
          "canonical_url": {
            "known": true,
            "value": "https://news.example.org/2026/11/live-link-roastery"
          },
          "published_at": {
            "known": false,
            "reason": "no_publication_date_found"
          },
          "charged": false,
          "unknowns": [
            {
              "field": "text.found",
              "reason": "text_not_supplied_link_check_mode"
            },
            {
              "field": "text.matched_phrase",
              "reason": "text_not_supplied_link_check_mode"
            },
            {
              "field": "text.match_zone",
              "reason": "text_not_supplied_link_check_mode"
            },
            {
              "field": "published_at",
              "reason": "no_publication_date_found"
            }
          ]
        }
      ],
      "rejected": [],
      "summary": {
        "verdicts": {
          "LINK_LIVE": 1
        },
        "headline": {
          "verdict": "LINK_LIVE",
          "pages": 1,
          "distinct_domains": 1
        }
      },
      "credits": {
        "held": 0,
        "charged": 0,
        "free_pages": 0
      },
      "failure_code": null,
      "metadata": {},
      "created_at": "2026-11-02T09:30:00Z",
      "started_at": "2026-11-02T09:30:02Z",
      "completed_at": "2026-11-02T09:30:03Z"
    }
    • verdict says what we found. LINK_LIVE means the page is live and links to your site.
    • links.items shows the link with its rel exactly as the page has it.
    • disclosure says whether a paid label was found and where.
    • fetched_at is the time we checked. It is the age of the answer.
    • A known: false value is something we could not observe, with the reason. Here the text was not checked because a link check takes no text. We never fill an unknown with a guess.
  4. Try your own pages

    Change the page address and run it again. In test mode the answer follows the words in the path, such as not-live or unverifiable; the test mode page lists them all. Add a text of at least 40 words to check for your text as well.

    Try it in the console if you prefer a form.

  5. Go live

    A live key starts with pp_live_. The code stays the same; only the key changes, and the pages are really fetched. Live checks are paid from your balance: see Credits and pricing.