Put AI detection inside your product

1. 1

   Step 1: Create a key

   Open Developers in the dashboard and create an API key.

2. 2

   Step 2: Send some text

   POST at least 40 words to /api/v1/detect.

3. 3

   Step 3: Read the result

   Use human_score for the overall call and sentences for highlights.

Conventions

Base URL

https://winstonai.com/api/v1

Format

JSON request and response bodies in UTF-8, snake_case field names, timestamps in ISO 8601 UTC.

Versioning

The version is part of the path. Within v1 we only add fields, never remove or rename them, so ignore any field you don't recognize.

Safe retries

Send an Idempotency-Key header, up to 255 characters, with any POST. Repeating the request with the same key and body within 24 hours replays the first response, marked Idempotent-Replayed: true, instead of scanning and charging twice.

OpenAPI

GET /api/v1/openapi.json returns an OpenAPI 3.1 description of every endpoint, with no key needed, so you can generate a client from it. Open the spec.

Request ids

Every response carries an X-Request-Id header. Include it when you contact support.

Limits

• Text per request40 to 25,000 words
• Images, coming soonUp to 10 MB: JPEG, PNG, WebP or HEIC
• Requests60 per minute for each API key
• Plagiarism scans10 running at once per workspace

Response headers

POSThttps://winstonai.com/api/v1/detect

Body parameters

textstringRequired

The text to check, from 40 to 25,000 words.

languagestring

ISO 639-1 code such as en or fr. Detected automatically when left out.

titlestring

A name for the scan, shown in your dashboard. Up to 200 characters.

authorstring

Who wrote the text. Up to 120 characters.

folder_idstring

Save the scan into one of your dashboard folders. An unknown id fails with invalid_body.

sentencesboolean

Include the per-sentence results. Defaults to true; set false to leave sentences out of the result.

metadataobject

Up to 20 string key-value pairs, such as your own submission id. Returned with the scan and in webhooks.

curl https://winstonai.com/api/v1/detect \
  -H "Authorization: Bearer $WINSTONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Remote work has become a cornerstone of modern business, offering employees unparalleled flexibility and a better balance between work and home. Moreover, it enables organizations to tap into a diverse, global talent pool. I still miss the office coffee, though, and the chats that only happen by accident.",
    "title": "Remote work essay"
  }'

Response

{
  "id": "scn_6f1c2a9e4b7d4c1e9a3f5b8d2e7c4a10",
  "object": "scan",
  "type": "ai_text",
  "status": "completed",
  "credits_used": 48,
  "metadata": {},
  "created_at": "2026-10-18T09:24:11Z",
  "completed_at": "2026-10-18T09:24:12Z",
  "result": {
    "human_score": 47,
    "verdict": "mixed",
    "word_count": 48,
    "sentence_count": 3,
    "readability": 66,
    "language": "en",
    "sentences": [
      {
        "text": "Remote work has become a cornerstone of modern business, offering employees unparalleled flexibility and a better balance between work and home.",
        "ai_probability": 0.755,
        "verdict": "ai"
      },
      {
        "text": "Moreover, it enables organizations to tap into a diverse, global talent pool.",
        "ai_probability": 0.524,
        "verdict": "mixed"
      },
      {
        "text": "I still miss the office coffee, though, and the chats that only happen by accident.",
        "ai_probability": 0.218,
        "verdict": "human"
      }
    ]
  },
  "error": null
}

The result object

human_scoreinteger

0 to 100. Higher means more likely written by a person.

verdictstring

human when human_score is 60 or more, mixed from 35 to 59, ai below 35.

sentences[].ai_probabilitynumber

0 to 1, to three decimal places. How likely this sentence is to be machine-written.

sentences[].verdictstring

ai from 0.65, mixed from 0.40, otherwise human. Use it to color highlights.

readabilityinteger

Reading ease, from 0 (hard) to 100 (easy).

languagestring | null

ISO 639-1 code of the language the text was scored as, or null if it couldn't be detected.

word_count, sentence_countinteger

Counts for the text that was scanned.

POSThttps://winstonai.com/api/v1/plagiarism

Body parameters

textstringRequired

The text to compare against web pages and your library, from 40 to 25,000 words.

titlestring

A name for the scan, shown in your dashboard. Up to 200 characters.

authorstring

Who wrote the text. Up to 120 characters.

folder_idstring

Save the scan into one of your dashboard folders. An unknown id fails with invalid_body.

exclude_urlsstring[]

Sources to ignore, such as the writer's own site. Up to 50 URLs.

exclude_quotesboolean

Skip text inside quotation marks. Defaults to true.

metadataobject

Up to 20 string key-value pairs, such as your own submission id. Returned with the scan and in webhooks.

curl https://winstonai.com/api/v1/plagiarism \
  -H "Authorization: Bearer $WINSTONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Remote work has become a cornerstone of modern business, offering employees unparalleled flexibility and a better balance between work and home. Moreover, it enables organizations to tap into a diverse, global talent pool. I still miss the office coffee, though, and the chats that only happen by accident.",
    "metadata": {
      "submission_id": "essay-1042"
    }
  }'

Response

{
  "id": "scn_b3e07d5a1c9f4e2d8a6b0c4f7e1d9a35",
  "object": "scan",
  "type": "plagiarism",
  "status": "queued",
  "credits_used": 96,
  "metadata": {
    "submission_id": "essay-1042"
  },
  "created_at": "2026-10-18T09:26:40Z",
  "completed_at": null,
  "result": null,
  "error": null
}

GEThttps://winstonai.com/api/v1/scans/{id}

Path parameters

idstringRequired

The scan id returned when you created the scan: scn_ followed by 32 hex characters.

curl https://winstonai.com/api/v1/scans/scn_b3e07d5a1c9f4e2d8a6b0c4f7e1d9a35 \
  -H "Authorization: Bearer $WINSTONAI_API_KEY"

Response

{
  "id": "scn_b3e07d5a1c9f4e2d8a6b0c4f7e1d9a35",
  "object": "scan",
  "type": "plagiarism",
  "status": "completed",
  "credits_used": 96,
  "metadata": {
    "submission_id": "essay-1042"
  },
  "created_at": "2026-10-18T09:26:40Z",
  "completed_at": "2026-10-18T09:27:05Z",
  "result": {
    "similarity": 22.9,
    "word_count": 48,
    "matched_words": 11,
    "sources": [
      {
        "url": "https://example.com/blog/remote-hiring-guide",
        "title": "A practical guide to hiring remotely",
        "type": "web",
        "matched_words": 11,
        "percent": 22.9,
        "excerpt": "it enables organizations to tap into a diverse, global talent pool"
      }
    ]
  },
  "error": null
}

The scan object

idstring

Unique id: scn_ followed by 32 hex characters.

typestring

ai_text, plagiarism or ai_image.

statusstring

queued, processing, completed or failed.

credits_usedinteger

Credits charged for this scan. Refunded if it fails.

resultobject | null

The findings, once status is completed. Its shape depends on type.

errorobject | null

A code and message, when status is failed.

metadataobject

Whatever you sent when creating the scan.

created_at, completed_atstring

ISO 8601 timestamps in UTC.

The plagiarism result

similaritynumber

0 to 100, to one decimal place. The share of words that match at least one source.

matched_wordsinteger

How many words match a source.

sources[].typestring

web for a public web page; document for a match in your own workspace library.

sources[].urlstring | null

Link to the source. null for documents in your workspace.

sources[].percentnumber

Share of your text that matches this source, to one decimal place.

sources[].matched_wordsinteger

Words in your text that match this source.

sources[].excerptstring | null

The matching passage, when one is available.

GEThttps://winstonai.com/api/v1/usage

curl https://winstonai.com/api/v1/usage \
  -H "Authorization: Bearer $WINSTONAI_API_KEY"

Response

{
  "object": "usage",
  "workspace_id": "6f1c2a9e-4b7d-4c1e-9a3f-5b8d2e7c4a10",
  "plan": "advanced",
  "credits": {
    "balance": 154230,
    "monthly_allowance": 200000
  },
  "rate_limit": {
    "limit": 60,
    "remaining": 59,
    "reset": 42
  }
}

planstring

free, essential, advanced or team.

credits.balanceinteger

Credits left to spend right now.

credits.monthly_allowanceinteger

Credits your plan adds each month.

rate_limitobject

limit, remaining and reset (seconds), the same as the rate limit headers.

POSThttps://winstonai.com/api/v1/image

Body parameters

urlstring

A public HTTPS link to a JPEG, PNG, WebP or HEIC image up to 10 MB. Send this or file.

filefile

The image itself, sent as multipart/form-data. Send this or url.

metadataobject

Up to 20 string key-value pairs, such as your own submission id. Returned with the scan and in webhooks.

curl https://winstonai.com/api/v1/image \
  -H "Authorization: Bearer $WINSTONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/uploads/product-shot.png"
  }'

Upload a file instead

curl https://winstonai.com/api/v1/image \
  -H "Authorization: Bearer $WINSTONAI_API_KEY" \
  -F "file=@photo.png"

Response

{
  "id": "scn_0d8e4f2a7c1b4e9d93a5f6c8b2e0d471",
  "object": "scan",
  "type": "ai_image",
  "status": "completed",
  "credits_used": 300,
  "metadata": {},
  "created_at": "2026-10-18T09:31:02Z",
  "completed_at": "2026-10-18T09:31:04Z",
  "result": {
    "human_score": 4,
    "verdict": "ai",
    "ai_probability": 0.96,
    "format": "png",
    "width": 1024,
    "height": 1024
  },
  "error": null
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This scan needs 2,360 credits and your balance is 420.",
    "cost": 2360,
    "balance": 420,
    "request_id": "req_5bT1kz0Qe2"
  }
}

Error types

Error codes

1. 1Step 1: In the Webhooks section of the Developers page, add your endpoint URL and pick the events you want. Send a test event to check it.
2. 2Step 2: Copy that endpoint's signing secret, which starts with whsec_, into your server's environment.
3. 3Step 3: On every delivery, verify the signature, then reply with any 2xx status within 10 seconds.

{
  "id": "evt_9sK1mP4rTbX2cQ7vN3wL8yZd",
  "object": "event",
  "type": "scan.completed",
  "created_at": "2026-10-18T09:27:05Z",
  "data": {
    "id": "scn_b3e07d5a1c9f4e2d8a6b0c4f7e1d9a35",
    "object": "scan",
    "type": "plagiarism",
    "status": "completed",
    "credits_used": 96,
    "metadata": {
      "submission_id": "essay-1042"
    },
    "created_at": "2026-10-18T09:26:40Z",
    "completed_at": "2026-10-18T09:27:05Z",
    "result": {
      "similarity": 22.9,
      "word_count": 48,
      "matched_words": 11,
      "sources": [
        {
          "url": "https://example.com/blog/remote-hiring-guide",
          "title": "A practical guide to hiring remotely",
          "type": "web",
          "matched_words": 11,
          "percent": 22.9,
          "excerpt": "it enables organizations to tap into a diverse, global talent pool"
        }
      ]
    },
    "error": null
  }
}

Delivery headers

Verify the signature

import crypto from "node:crypto";

// rawBody: the exact request body as a string, before JSON parsing.
export function verifyWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery and retries

• Deliveries that time out or get a non-2xx reply are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 15 hours: seven attempts over about a day.
• An event can arrive more than once or out of order. Store the event id and skip ones you have already handled.
• Each endpoint has its own signing secret, so check deliveries with the secret of the endpoint they reached.