API Documentation

AI Text Detection API

Complete documentation for integrating TruthScan's AI 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.

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

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

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.

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

wss://detect-text.truthscan.com/ws/$USER_ID

You must replace $USER_ID with your personal User Id.

AI Detector

Detect

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

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

Threshold

This endpoint returns a "result" score from 1-100. For best accuracy, any score under 50 is considered definitely human. 50-60 is possible AI. Over 60 is definite AI. This is the most accurate result, with 99%+ accuracy.

The scores for other detectors, such as Writer and Copyleaks, are approximate and not as accurate as the main "result" score.

Line breaks

If you're sending data as JSON, line breaks should be encoded as \n inside the string.

Example Request

curl -X 'POST' \
  'https://detect-text.truthscan.com/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.

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

{
    "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": 12.0 indicates the human-ness of the input. This means that given it is less than the 50% threshold, the text is definitely human. 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.

GET https://detect-text.truthscan.com/check-user-credits

Example Request

curl -X 'GET' \
  'https://detect-text.truthscan.com/check-user-credits' \
  -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

Connect to the WebSocket

This endpoint allows you to establish the WebSocket connection

wss://detect-text.truthscan.com/ws/$USER_ID

Example code

ws = new WebSocket("wss://detect-text.truthscan.com/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

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

Example Request

curl -X 'POST' \
  'https://detect-text.truthscan.com/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": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

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": "xlm_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": "xlm_ud_detector"
}

Handling exceptional circumstances

If for some reason the server encounters an error while performing AI detection, 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"
}

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 (0.1 per word).
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.

Common Issues and Solutions

Authentication Issues

"User verification failed" (403)

Cause: Invalid or expired API key

Solution:

Verify your API key is correct
Check if your API key is active in your account
Try regenerating your API key

"Not enough credits" (403)

Cause: Insufficient credits for text processing

Solution:

Check your remaining credits using /check-user-credits
Purchase additional credits if needed
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:

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

"Input email is empty" (400)

Cause: Missing email for URL processing

Solution:

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

Processing Issues

"Request timeout" (WebSocket)

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

Solution:

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

Document Status "failed"

Cause: Processing failed for various reasons

Solution:

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

WebSocket Connection Issues

Connection Drops

Cause: Network issues or server disconnects

Solution:

Check your network connection
Implement reconnection logic
Verify WebSocket URL is correct

"User not found" (WebSocket)

Cause: Invalid user ID in WebSocket connection

Solution:

Verify user ID is correct
Ensure user account is active
Re-authenticate if needed

Need Help?

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

How do I get an API key?

You can get your API key by visiting your account in the TruthScan developer portal. The API key is available at the top of your account page.

What is the word limit for AI detection?

The input limit for the /detect endpoint is 30,000 words. We recommend at least 200 words for best accuracy.

How does the credits system work?

Each detection request consumes credits from your account. You can check your available credits using the /check-user-credits endpoint. Credits are automatically replenished according to your subscription plan.

How long does it take to process a detection?

The average time to complete an AI Detection check is between 2-4 seconds. Processing time may vary depending on word count and server load.

Can I use WebSockets for real-time detection?

Yes, TruthScan offers WebSocket support for real-time detection. You'll need to include your User ID in the WebSocket URL. See the Authentication section for more details.

What AI models are supported?

TruthScan uses the xlm_ud_detector model as default, which offers 99%+ accuracy. The endpoint also returns scores from various other third-party detectors including GPTZero, Writer, CopyLeaks, and others.

How do I handle connection errors?

For WebSockets, we recommend implementing automatic reconnection logic. For REST requests, use retry_count in the request body to allow automatic retries. Always check the status response before processing results.

Is there a rate limit for API requests?

Rate limits depend on your subscription plan. Contact us for more information about rate limits for your specific plan or visit our pricing page.

API Frequently Asked Questions

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

You can get your API key by visiting your account in the TruthScan developer portal. The API key is available at the top of your account page.