API Documentation

AI PDF Detection API

Complete documentation for integrating TruthScan's AI PDF detection API into your applications.

Try it out without code by visiting our FastAPI endpoint: https://detect-text.truthscan.com/docs

Pricing & credits

PDF detection deducts 1,000 credits per page (e.g. a 5-page PDF uses 5,000 credits).

Check your balance with GET /check-user-credits. View pricing plans

Authentication

TruthScan uses API keys to allow access to the API. You can get your API key at the top of the page in our developer portal.

For presigned upload URL requests (`GET /get-presigned-url`), include your API key in the `apikey` header.

For PDF detection requests (`POST /detect-pdf`), include your API key in the JSON body as `key`.

You must replace YOUR API KEY GOES HERE with your personal API key.

PDF Detector

The PDF Detector analyzes uploaded PDF documents for signs of AI generation and digital tampering. PDFs are processed asynchronously, upload your file, submit it for detection via `/detect-pdf`, then poll for results.

The detector runs multiple analysis modules on each document. By default all modules run. You can choose which modules to run by including the `modules` parameter in your request:

Metadata: metadata
Checks document metadata for tampering artifacts left by AI or digital editing tools.
Structure: structure
Inspects the document for digital edits such as hidden text layers.

Model selection

Send `model` in the request body as one of the values below. Any other value returns 400 Bad Request.

pdf_detector: Latest version (currently `pdf_detector/v5`). Same as omitting `model`.
pdf_detector/v1: Detects whether the PDF was generated by an AI tool in PDF metadata.
pdf_detector/v3: Checks for digital edits and signs of AI-generated documents.
pdf_detector/v4: Checks for digital edits and signs of AI-generated documents, with improved overall performance over v3.
pdf_detector/v5: Latest detector. Runs metadata and structure analysis.

Module selection

Send `modules` in the request body as one of the values below.

[]: All modules (default). Same as omitting `modules`.
["metadata"]: Metadata analysis only.
["structure"]: Structure analysis only.

Workflow

Get a presigned upload URL: `GET /get-presigned-url`
Upload the PDF: `PUT` the file bytes to the presigned URL
Submit for detection: `POST /detect-pdf`
Poll for results: `POST /query` with the returned document `id` until `status` is `done`

File requirements

Files must be `.pdf` format, at most 2 MB, and publicly reachable at the URL you provide.

Credits deduction

PDF detection consumes 1,000 credits per page regardless of which modules are selected. A 5-page PDF costs 5,000 credits. Check your balance with `GET /check-user-credits` before submitting large documents.

Step 1 : Get a Presigned Upload URL

Request a presigned upload URL before submitting a PDF for detection. `file_name` (required): the PDF file name (must end in `.pdf`). `expiration` (optional): URL expiration time in seconds (default: 3600).

Headers

Include your API key in the `apikey` header.

GET https://detect-text.truthscan.com/get-presigned-url

Example Request

curl -X 'GET' \
  'https://detect-text.truthscan.com/get-presigned-url?file_name=report.pdf&expiration=3600' \
  -H 'accept: application/json' \
  -H 'apikey: YOUR-API-KEY-GOES-HERE'

Upload the file with a PUT to the `presigned_url` from the response before calling `/detect-pdf`.

Example Response

{
    "status": "success",
    "presigned_url": "https://...digitaloceanspaces.com/...?X-Amz-Algorithm=...",
    "file_path": "userId_20250604120000_report.pdf"
}

Step 2 : Upload the PDF

Use the provided `presigned_url` to upload your PDF via a `PUT` request.

Example Request

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_report.pdf...' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@report.pdf'

Step 3 : Submit for Detection

Submit a PDF that has already been uploaded to object storage.

Request body

url (required): The object-storage URL of the uploaded PDF (the `presigned_url` host + `file_path`).
key (required): Your API key.
model: The detector model to use. Defaults to `pdf_detector` (latest). Supported versioned values include `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4`, and `pdf_detector/v5`.
modules: Array of modules to run: `["metadata"]`, `["structure"]`, or `["metadata", "structure"]`. Omit or send `[]` to run all. Applies to v4 and v5; ignored for legacy versions.

POST https://detect-text.truthscan.com/detect-pdf

Example Request : all modules (default)

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect-pdf' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-bucket.region.digitaloceanspaces.com/userId_20250604120000_report.pdf",
  "key": "YOUR-API-KEY-GOES-HERE"
}'

Example Request : metadata only

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect-pdf' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-bucket.region.digitaloceanspaces.com/userId_20250604120000_report.pdf",
  "key": "YOUR-API-KEY-GOES-HERE",
  "modules": ["metadata"]
}'

Example Response

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

The response contains a document `id`. Use it to poll for results via `POST /query`. Processing typically completes within a few seconds.

Step 4 : Poll for Results

Use the `/query` endpoint (same as text detection) to check status and retrieve results. Response shape depends on which `model` was used for the job. Poll until `status` is `done`.

POST https://detect-text.truthscan.com/query

Example Request

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-FROM-STEP-3"
}'

Example Response : Tampered document

{
    "id": "594502f3-5474-4d2f-9a7a-039f85485854",
    "model": "pdf_detector",
    "status": "done",
    "retry_count": 0,
    "modules": {
        "metadata": {
            "status": "done",
            "result_details": {
                "prediction": "ChatGPT",
                "rule": "PyMuPDF - Creator: OpenAI",
                "base_category": "Possibly AI Generated/Edited",
                "basic_source": "ChatGPT"
            },
            "source_details": {
                "source": "AI Generated",
                "credits_deducted": 1000
            },
            "label": "Tampered"
        },
        "structure": {
            "status": "done",
            "result_details": {
                "prediction": "Suspicious",
                "rule": { "hidden": "medium" },
                "max_severity": "medium",
                "signals_flagged": 1,
                "signals": {
                    "hidden": {
                        "label": "Hidden Text",
                        "flagged": true,
                        "severity": "medium",
                        "findings": [
                            {
                                "severity": "medium",
                                "detail": "Page 1: invisible text layer found beneath visible content."
                            }
                        ]
                    }
                }
            },
            "detailed_explanation": "Page 1 contains a hidden text layer beneath visible content, suggesting possible content manipulation.",
            "label": "Suspicious"
        }
    },
    "summary": {
        "label": "Tampered",
        "detection_steps": ["metadata", "structure"],
        "detection_rules": {
            "metadata": "PyMuPDF - Creator: OpenAI",
            "structure": "1 signals fired"
        },
        "details": {
            "is_ai": true,
            "ai_detection_steps": ["metadata"],
            "is_digitally_edited": true,
            "digital_edit_detection_steps": ["structure"]
        }
    }
}

Metadata module

label: Tampered if an AI fingerprint was found; Genuine otherwise.
result_details.prediction: The identified AI tool (e.g. `"ChatGPT"`) or `"No Tampering Detected"`.
source_details: Nested inside `modules.metadata`.
source_details.source: `"AI Generated"`, `"Digitally Edited"`, or `null`.
source_details.credits_deducted: Credits charged for this job on TruthScan keys; `null` otherwise.

Example Response: Genuine document

{
    "id": "e4c0f5d7-b061-4d4e-af9c-5b8da03e6f44",
    "model": "pdf_detector",
    "status": "done",
    "retry_count": 0,
    "modules": {
        "metadata": {
            "status": "done",
            "result_details": {
                "prediction": "No Tampering Detected",
                "rule": null,
                "base_category": "No Tampering Detected",
                "basic_source": null
            },
            "source_details": {
                "source": null,
                "credits_deducted": 1000
            },
            "label": "Genuine"
        },
        "structure": {
            "status": "done",
            "result_details": {
                "prediction": "Genuine",
                "rule": {},
                "max_severity": null,
                "signals_flagged": 0,
                "signals": {
                    "hidden": {
                        "label": "Hidden Text",
                        "flagged": false,
                        "severity": null,
                        "findings": []
                    }
                }
            },
            "detailed_explanation": "No AI-generation or tampering fingerprints were detected; the PDF looks clean.",
            "label": "Genuine"
        }
    },
    "summary": {
        "label": "Genuine",
        "detection_steps": [],
        "detection_rules": {},
        "details": {
            "is_ai": false,
            "ai_detection_steps": [],
            "is_digitally_edited": false,
            "digital_edit_detection_steps": []
        }
    }
}

Understanding the Response

`summary.label` is the overall verdict. `summary.detection_steps` lists modules that flagged the document. `summary.detection_rules` records what triggered each flagged module. `summary.details.is_ai` is `true` if the document was identified as AI-generated. `summary.details.is_digitally_edited` is `true` if structural edits were detected.

Structure module

label: Tampered, Suspicious, or Genuine.
result_details.signals: Per-signal breakdown. `hidden` detects hidden text layers in the document.
result_details.signals_flagged: Total number of signals that fired.
detailed_explanation: Human-readable summary of the findings.

Verdict

Tampered: Strong evidence of content manipulation or AI-generated origin.
Suspicious: One or more signals detected, but not at the highest confidence level.
Genuine: No tampering signals detected.

Severity levels

Each individual finding carries a severity level: `"low"`, `"medium"`, or `"high"`.

Errors

Most errors will be from incorrect parameters being sent to the API. Double check the parameters of each API call to make sure it's properly formatted, and try running the provided example code.

The generic error codes we use conform to the REST standard:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
403	Forbidden -- The API key is invalid, or there aren't sufficient credits (1,000 per PDF page).
404	Not Found -- The specified resource doesn't exist.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
410	Gone -- The resource at this endpoint has been removed.
422	Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters.
429	Too Many Requests -- You're sending too many requests! Slow it down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Pricing

Get full forensic reports - heat maps, key indicators, and detailed descriptions.

Free

$0/month

Try the full engine

25 results/month (images + PDF pages)
Detailed indicators on every result
Full API access
Detection history in dashboard
Free forever — no trial period
Chrome extension, unlimited seats

Starter

$24/month

$0.03 / result - $290/yr

For individuals and small teams

1,000 results/month included
$0.03 per additional result
CSV export of result history
Batch uploads
Audit-ready detection reports
Standard support
Chrome extension, unlimited seats

Customize a Plan For Your Needs

$0.005 or less per result

Contact Sales

Discounts scale with volume
Custom SLAs with service credits
Zero Data Retention (ZDR)
Custom integrations

Custom MSA and DPA
Dedicated throughput
Named 24/7 account team
Dedicated / on-prem deployment

API Frequently Asked Questions

Find answers to the most common questions about our AI PDF detection API.

AI PDF Detection API

Authentication

PDF Detector

Step 1 : Get a Presigned Upload URL

Step 2 : Upload the PDF

Step 3 : Submit for Detection

Step 4 : Poll for Results

Errors

Pricing

Customize a Plan For Your Needs

API Frequently Asked Questions

How do I get an API key?

What are the PDF file requirements?

How are credits deducted for PDF detection?

How long does PDF detection take?

What is the difference between v1 and v3/v4 PDF detection?