API Documentation
ISO 27001SOC 2 CertifiedGDPR Compliant

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 files asynchronously. PDFs must be uploaded to object storage first, then submitted via `/detect-pdf`. Poll `/query` until `status` is `done`.

Three detector versions are available. Each answers a different question, pick the one that matches your use case (or run both v1 and v3/v4 on the same file by submitting twice with different `model` values):

  • v1: pdf_detector/v1

    Detects whether the PDF was generated by an AI tool in PDF metadata.

  • v3: pdf_detector/v3

    Checks for digital edits and signs of AI-generated documents.

  • v4: pdf_detector/v4 (default / latest)

    Latest version of the tampering detector with improved overall performance and recommended for new integrations.

Model selection

  • pdf_detector: Omit `model`, or send `pdf_detector`, to use the latest version (currently `pdf_detector/v4`).
  • pdf_detector/v1: Send `model: pdf_detector/v1` for AI-generation metadata detection.
  • pdf_detector/v3: Send `model: pdf_detector/v3` to pin v3.
  • pdf_detector/v4: Send `model: pdf_detector/v4` to pin v4 explicitly.
  • model: Any other `model` value returns 400 Bad Request.

Workflow

  • `GET /get-presigned-url` with a `.pdf` file name and your API key in the `apikey` header.
  • `PUT` the PDF bytes to the returned `presigned_url`.
  • `POST /detect-pdf` with the public object `url`, your API `key`, and an optional `model`.
  • `POST /query` with the returned document `id` until processing completes.

File limits

PDF files must be `.pdf`, at most 2 MB, and reachable at the `url` you submit.

Credits deduction

PDF detection deducts 1,000 credits per page. A 5-page PDF consumes 5,000 credits. Check your balance with `/check-user-credits` before submitting large documents.

Obtain a Pre-signed Upload URL

Request a presigned upload URL before submitting a PDF for detection.

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"
}

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'

Detect PDF

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

Request body

  • url (required): Public object-storage URL of the uploaded PDF.
  • key (required): Your API key.
  • model: `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4`, or `pdf_detector` (latest). Defaults to `pdf_detector/v4`.
POST https://detect-text.truthscan.com/detect-pdf

Example Request : default (v4 / latest)

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 : pin to v1 (AI-generation metadata)

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",
  "model": "pdf_detector/v1"
}'

Example Response

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

The response contains the server-assigned document ID. Use `POST /query` to poll for results. Typical completion time is a few seconds.

Query

Poll PDF detection status and results by document ID (same endpoint as text detection). Response shape depends on which `model` was used for the job.

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-GOES-HERE"
}'

Example Response: v1 AI fingerprint found

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "Tampering Detected",
    "result_details": {
        "prediction": "Grok",
        "base_category": "Possibly AI Generated/Edited"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": null
    },
    "retry_count": 0
}

v1 fields

  • label: "Tampering Detected" when flagged; "No Tampering Detected" otherwise.
  • result_details.prediction: Specific tool name (e.g. "Grok", "ChatGPT"), generic "AI Generated", or "No Tampering Detected".
  • result_details.base_category: "Possibly AI Generated/Edited" or "No Tampering Detected".
  • source_details.source: Attributed source on a hit; null when no fingerprint is found.

Example Response: v1 no AI fingerprint

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "No Tampering Detected",
    "result_details": {
        "prediction": "No Tampering Detected",
        "base_category": "No Tampering Detected"
    },
    "result_categories": null,
    "source_details": null,
    "retry_count": 0
}

Example Response: v3 structural tampering detected

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Tampered",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Tampered",
            "rule": { "hidden": "high" },
            "max_severity": "high",
            "signals_flagged": 1,
            "signals": {
                "hidden": {
                    "label": "Hidden Text",
                    "flagged": true,
                    "severity": "high",
                    "findings": [
                        {
                            "severity": "high",
                            "detail": "Invisible or off-page text detected on page 1."
                        }
                    ]
                }
            }
        },
        "detailed_explanation": "Hidden text was found on page 1 that is not visible in the rendered document."
    }
}

Example Response: v3 no tampering detected (Genuine)

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Genuine",
    "result_details": {
        "status": "ok",
        "structure": {
            "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."
    }
}

Example Response: v4 (same format as v3)

v4 returns the same response shape as v3. The `model` field will show `pdf_detector/v4`.

v3 / v4 fields

  • label: Mirrors `structure.prediction`: "Tampered", "Suspicious", or "Genuine".
  • result_details.structure.signals: Breakdown for the `hidden` signal. Includes `label`, `flagged`, `severity`, and `findings` (with optional `changes` showing before/after values when available).
  • result_details.detailed_explanation: Plain-language summary of the findings.

Verdict tiers

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

Severity levels

Each finding uses `"low"`, `"medium"`, or `"high"` to indicate confidence.

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

Need Help?

For more information about using our API or for technical support, please contact us.

Contact Us

API Frequently Asked Questions

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