Try it Out

You can test out the API without code by going to the FastAPI link with your web browser: https://ai-detect.undetectable.ai/docs

Authentication

Undetectable.AI 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.

UD expects for the API key to be included in all API requests to the server in a request body that looks like the following:

key: YOUR API KEY GOES HERE

For web socket scenarios, you will need to send the users id as part of the url. You can get your User ID at the top of the page in our developer portal.

UD expects for the users User ID to be included in the url of all web socket requests. The documentation will look like the following:

AI Detector

Detect

This endpoint allows you to submit text for AI detection. At least 200 words are recommended for best accuracy.

On Citizen science
Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.

Example Request

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0
}'

Here, the request input must be less than 30,000 words.

Example Response

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

The response contains the server-assigned ID of the document. At this point the document is now enqueued for processing. You can use the /query API endpoint to query the status of the AI Detection request. The average time to complete an AI Detection check is between 2-4 seconds. It may take longer depending on word count.

Query

This endpoint accepts a document id returned by the /detect request. And returns the status of the document submission as well as the result of the AI Detection operation as handled by various third-party AI detectors.

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

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0
    },
    "status": "done",
    "retry_count": 0
}

Here, "result": 88.0 indicates the AI-ness of the input. This means that given it is greater than the 50% threshold, the text is AI-generated. Similarly the values under the result_details indicate the Human-ness of the input. For example "scoreZeroGPT": 50.0 signifies that the text is likely 50% human-written as per ZeroGPT. The Same goes for the rest of the other detectors.

Check User Credits

This endpoint accepts the users apikey via the header. And returns users credit details.

Example Request

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/query' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \

Example Response

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Sentence Level AI Detection

The sentence-level AI Detector runs on top of a WebSocket-based protocol.

Here are the necessary steps needed to get sentence-level results for your text.

• Connect to the WebSocket
• Listen for all events received from the WebSocket
• Send a document_watch request
• Receive a document_id event
• Take the id generated by the document_id response and submit a document for AI Detection
• Start receiving document_chunk events. document_chunk events will return each sentence together with the sentence-level result
• When the document finishes processing, you will receive a document_done event.

This section will describe the necessary steps to connect, send a document for processing, and listen to the sentence stream until it finishes.

Connect to the WebSocket

This endpoint allows you to establish the WebSocket connection

Example code:

ws = new WebSocket("wss://https://ai-detect.undetectable.ai/ws/1722238709737x2194626580942121212");

Listen for all events received from the WebSocket

Once the WebSocket connection is established, listen to events sent through the WebSocket connection.

Example code:

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Send a document_watch request

Send interest in sending a document by sending a document_watch request on the WebSocket

Example code:

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Receive a document_id event

After sending a document_watch event, the server returns a document_id event.

Example response:

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Submit an AI Detection Request

Take the id generated by the document_id response and submit a document for AI Detection

Example Request

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xIm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Example Response

{
    "id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xIm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Receive sentence level results

Start receiving document_chunk events. document_chunk events will return each sentence together with the sentence level result

Example responses:

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
    "model": "xIm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

When the document finishes processing, you will receive a document_done event.

Example responses:

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
    "model": "xIm_ud_detector"
}

Below is an example sequence as returned by the WS stream.

Handling exceptional circumstances

If for some reason the server encounters an error while doing the humanization, a document_error event will be sent to the websocket client. The client should act as appropriate, for example a UI will show an error message.

For example, the server will send a REQUEST_TIMEOUT error code when it takes more than 20 seconds across chunk events.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds.",
}

Cancellations

There will be instances when the UI would want to cancel the operation. The user decides to close the window, or cancels the event explicitly
When this happens you should sent a document_halt event

Example responses:

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

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):

Obtain a Pre-signed Upload URL

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

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'

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.

Example Request : default (v4 / latest)

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

Example Request : pin to v1 (AI-generation metadata)

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

Example Response

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_detector/v3",
    "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.

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.

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: v1 AI fingerprint found

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "result": 100.0,
    "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
}

Example Response: v1 no AI fingerprint

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "result": 0.0,
    "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",
    "result": 100.0,
    "label": "Tampered",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Tampered",
            "rule": { "revision": "high" },
            "max_severity": "high",
            "signals_flagged": 1,
            "signals": {
                "overlay": { "label": "Overlay / Annotation Layer", "flagged": false, "severity": null, "findings": [] },
                "hidden": { "label": "Hidden Text", "flagged": false, "severity": null, "findings": [] },
                "font": { "label": "Font Anomalies", "flagged": false, "severity": null, "findings": [] },
                "revision": {
                    "label": "Incremental / Revision Tampering",
                    "flagged": true,
                    "severity": "high",
                    "findings": [
                        {
                            "severity": "high",
                            "detail": "Page content overwritten after creation.",
                            "changes": ["p1: '$1,250.00' -> '$5,750.00'"]
                        }
                    ]
                },
                "ai_origin": { "label": "AI Origin", "flagged": false, "severity": null, "findings": [] }
            }
        },
        "llm_explanation": "The amount on page 1 was changed from $1,250.00 to $5,750.00 after the document was created."
    }
}

Example Response: v3 AI-generated (engine marker escalation)

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "result": 100.0,
    "label": "Tampered",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Tampered",
            "rule": { "ai_origin": "high" },
            "max_severity": "high",
            "signals_flagged": 1,
            "signals": {
                "overlay": { "label": "Overlay / Annotation Layer", "flagged": false, "severity": null, "findings": [] },
                "hidden": { "label": "Hidden Text", "flagged": false, "severity": null, "findings": [] },
                "font": { "label": "Font Anomalies", "flagged": false, "severity": null, "findings": [] },
                "revision": { "label": "Incremental / Revision Tampering", "flagged": false, "severity": null, "findings": [] },
                "ai_origin": {
                    "label": "AI Origin",
                    "flagged": true,
                    "severity": "high",
                    "findings": [
                        {
                            "severity": "high",
                            "detail": "Document carries an AI-generation engine marker."
                        }
                    ]
                }
            }
        },
        "llm_explanation": "This document was generated by an AI tool."
    }
}

Example Response: v3 no tampering detected (Genuine)

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "result": 0.0,
    "label": "Genuine",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Genuine",
            "rule": {},
            "max_severity": null,
            "signals_flagged": 0,
            "signals": {
                "overlay": { "label": "Overlay / Annotation Layer", "flagged": false, "severity": null, "findings": [] },
                "hidden": { "label": "Hidden Text", "flagged": false, "severity": null, "findings": [] },
                "font": { "label": "Font Anomalies", "flagged": false, "severity": null, "findings": [] },
                "revision": { "label": "Incremental / Revision Tampering", "flagged": false, "severity": null, "findings": [] },
                "ai_origin": { "label": "AI Origin", "flagged": false, "severity": null, "findings": [] }
            }
        },
        "llm_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.

Errors

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

Common Issues and Solutions

Authentication Issues

"User verification failed" (403)

• Cause: Invalid or expired API key
• Solution:

1. Verify your API key is correct
2. Check if your API key is active in your account
3. Try regenerating your API key

"Not enough credits" (403)

• Cause: Insufficient credits for text processing
• Solution:

1. Check your remaining credits using /check-user-credits
2. Purchase additional credits if needed
3. Use shorter text inputs to consume fewer credits

Input Validation Issues

"Input text cannot be empty" (400)

• Cause: Empty or whitespace-only text submitted
• Solution:

1. Ensure your text input is not empty
2. Remove any leading/trailing whitespace
3. Check if text encoding is correct

"Input email is empty" (400)

• Cause: Missing email for URL processing
• Solution:

1. Provide a valid email address when submitting URLs
2. Check email format is correct

Processing Issues

"Request timeout" (WebSocket)

• Cause: Document processing took too long (>120 seconds)
• Solution:

1. Try with a smaller text input
2. Check if the service is experiencing high load
3. Retry the request

Document Status "failed"

• Cause: Processing failed for various reasons
• Solution:

1. Check if input text meets minimum requirements
2. Verify text is in a supported format
3. Try with a different model
4. Contact support if issue persists

WebSocket Connection Issues

Connection Drops

• Cause: Network issues or server disconnects
• Solution:

1. Check your network connection
2. Implement reconnection logic
3. Verify WebSocket URL is correct

"User not found" (WebSocket)

• Cause: Invalid user ID in WebSocket connection
• Solution:

1. Verify user ID is correct
2. Ensure user account is active
3. Re-authenticate if needed

Updated on: 13/07/2026