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

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

AI Detector

The AI Detector

Detect

This endpoint allows you to submit text for AI detection.

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

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

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": "detector_v2",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Here, 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.

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

{
    "id": "cad69516-bdae-4639-a96c-cb82525b247b",
    "model": "detector_v2",
    "result": 88.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, "human": 88.0 means that given our 0.7 threshold, about 60% of the text is AI-generated, while the remaining 40% is human-written. Similarly, "scoreZeroGPT": 50.0 signifies that the text is likely 50% human-written as per ZeroGPT. Same goes for the rest of the other detectors.

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 for the sentence stream until it finishes.

Connect to the websocket

This endpoint allows you to establish the websocket connection

POST https://ai-detect.undetectable.ai/ws/$USER_ID

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

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

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

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 isn'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 end point has been removed.
422	Invalid Request Body -- You're request body is formatted incorrectly or invalid or there are 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.

Updated on: 27/02/2025