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

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 for AI-generation fingerprints using PDF metadata (`/Creator`, `/Producer`). PDFs must be uploaded to object storage first, then submitted for async processing. Poll `/query` until `status` is `done`.

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` and your API `key` (`document_type` is set to PDF automatically).
`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. Other file types are rejected for this flow.

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://ai-detect.undetectable.ai/get-presigned-url

Example Request

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

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

Detect PDF

Submit a PDF that has already been uploaded to object storage. This endpoint enqueues metadata analysis and optional text AI detection.

Threshold

For PDF jobs (model: `pdf_metadata_detector`), `result` is always 100.0 (fingerprint matched → `label`: "AI") or 0.0 (no fingerprint → `label`: "Human"). The 50/60 human/AI thresholds only apply to text detection (model: `xlm_ud_detector`).

Response fields

Poll `/query` for the document. For PDF jobs (model: `pdf_metadata_detector`), `result_details` contains `prediction`, `rule`, `base_category`, and `basic_source` at the top level. The PDF's raw creator/producer values are not returned, they are used internally and reflected in `rule` when a pattern matches. `service_type` is always `detector`, and `model` remains `pdf_metadata_detector` for the lifetime of the job.

POST https://ai-detect.undetectable.ai/detect-pdf

Example Request

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/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",
  "retry_count": 0
}'

Optional Parameters

Pass `"id"` to supply your own document UUID (must not already exist).
Pass `"generate_analysis_details": true` to request deep text analysis when text AI runs (same behavior as text `/detect`).
You may also use `POST /detect` with `"document_type": "File"` for the same behavior.

Example Response

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_metadata_detector",
    "result": null,
    "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 for metadata-only jobs; jobs that also run text AI may take longer depending on extracted word count.

Query

Poll PDF detection status and results by document ID (same endpoint as text detection).

POST https://ai-detect.undetectable.ai/query

Example Request

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

Example Response (metadata AI detected)

{
    "id": "49b5a390-2285-47fe-a161-303b4e22406f",
    "model": "pdf_metadata_detector",
    "status": "done",
    "result": 100.0,
    "result_details": {
        "prediction": "Grok",
        "rule": "PyMuPDF - Creator: Grok xAI",
        "base_category": "Possibly AI Generated/Edited",
        "basic_source": "Grok"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": 1000
    },
    "retry_count": 0,
    "label": "AI"
}

When text AI also runs, `model` may be `xlm_ud_detector`, `result_details` includes both detector scores and `pdf_metadata`, and `source_details` may include merged metadata/text attribution.

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.

Need Help?

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

API Frequently Asked Questions

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