---
title: "Score and interpret text"
url: "https://stylome.io/api/docs/scoring"
---

> [Documentation index](https://stylome.io/llms.txt) · [API overview](https://stylome.io/api/docs)

# Score and interpret text

`POST https://stylome.io/api/v1/score` requires a Bearer credential with `score:create` and sufficient prepaid API credit. It analyzes one text. Do not submit private customer content until you have chosen the key's [retention policy](https://stylome.io/api/docs/billing-and-privacy).

## Request schema

| Field | Type | Meaning |
| --- | --- | --- |
| `text` | string, required | Text to analyze; 200–10,000 normalized Unicode characters |
| `model` | string, required | `stylome-1.2-large` or `stylome-1.0-large` |
| `operating_point` | string or null, optional | For 1.2 only: `0.01%` (default) or `0.1%`; omit for 1.0 |

Unknown JSON fields are rejected. For 1.2, whitespace is collapsed without Unicode compatibility normalization. Count the normalized text with Python `len(text)` semantics: Unicode code points, not bytes, tokens, or JavaScript UTF-16 code units. Inputs outside the limits return `422`; they are never silently truncated. The outer raw-text schema permits up to 100,000 characters, but that does not replace the normalized 10,000-character limit. The HTTP request-body limit is 131,072 bytes. Consult `GET /api/v1/models` for each model's normalization contract.

## Send your own text

Put the text you want to analyze in UTF-8 `text.txt`. This example builds valid JSON without hand-escaping the text. It makes a paid scoring call when executed; no result for this text is claimed here.

```bash
python3 - <<'PY' > request.json
import json
from pathlib import Path
text = Path("text.txt").read_text(encoding="utf-8")
print(json.dumps({"text": text, "model": "stylome-1.2-large"}))
PY
curl --fail-with-body --max-time 150 https://stylome.io/api/v1/score \
  --header "Authorization: Bearer $STYLOME_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

With a standard-retention key, add a unique `Idempotency-Key` for this logical operation and reuse it if you retry. Omit that header for a zero-content key. Read the [retry rules](https://stylome.io/api/docs/operations) before automating retries.

## Stylome 1.2 response schema

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | Scoring result identifier |
| `mock` | boolean | `false` for a real result |
| `label` | string | `human_written`, `ai_edited`, or `ai_generated` |
| `confidence` | string | `low`, `medium`, or `high` relative nearest-neighbor support |
| `content_hash` | string | Hash returned to the caller; not retained for zero-content keys |
| `model_version` | string | `stylome-1.2-large` |
| `created_at` | date-time string | Result creation time |
| `operating_point` | string | The selected `0.01%` or `0.1%` decision |
| `response_version` | string | Public schema identity, `stylome-public-v2` |
| `evaluation_version` | string | Opaque identity of the frozen evaluation configuration |
| `receipt` | object or null | If present: `id`, private `share_token`, and `public_share: false` |
| `usage` | object or null | Committed normalized characters and exact original-operation cost |

`usage` has `input_characters` (non-negative integer), `cost_usd` (decimal string with six places), `currency: "USD"`, and `pricing_version`. It can be null only for an idempotent replay from before prepaid billing. A replay returns the original cost without charging it again. Keep private receipt capabilities secret.

`human_written` means human-authored text without a material AI contribution. `ai_edited` means the final text retains material human authorship and includes an AI transformation. `ai_generated` means fully machine-derived text, including a machine rewrite or humanization with no material human-authored contribution. These are authorship classes, not percentages of AI-written words.

Confidence is not a probability of correctness. The operating points are calibration false-positive-rate targets, not confidence levels or guarantees on new data. The response includes only the selected decision and omits numerical diagnostics, internal model identities, and alternate decisions.

## Legacy Stylome 1.0

Select `stylome-1.0-large` to use its separate numerical contract. Omit `operating_point`. It does not compute the 1.2 KNN confidence. Do not interpret its legacy numerical fields as the 1.2 categorical contract or compare deployed outputs across models as matched-error-rate measurements.

The complete legacy schema is [ApiLegacyScore in OpenAPI](https://stylome.io/api/openapi.json#/components/schemas/ApiLegacyScore), also browsable in the [interactive reference](https://stylome.io/api/docs/interactive). The response is discriminated by `model_version`. Use the schema for the selected model rather than assuming both models return the same fields.

| Legacy field | Schema type |
| --- | --- |
| `id`, `content_hash`, `created_at` | String identifiers/hash and date-time |
| `mock`, `model_version` | `false`, `stylome-1.0-large` |
| `verdict` | `human_typical`, `mixed_signals`, or `ai_typical` |
| `score` | Number or null |
| `detector_score`, `threshold`, `margin` | Numbers |
| `label` | String |
| `probabilities` | Object mapping strings to numbers, or null |
| `binary_label`, `operating_point` | String or null |
| `operating_points` | Object or null |
| `confidence` | `low`, `medium`, `high`, or null in the compatibility schema; not computed for 1.0 |
| `confidence_evidence`, `uncertainty`, `knn_decision` | Object or null |
| `classification_contract`, `confidence_contract`, `confidence_artifact_sha256`, `scoring_contract`, `model_revision` | String or null |
| `receipt` | Object with `id`, `share_token`, and `public_share: false`, or null |
| `usage` | The same billing object described above, or null for historical replay |

Nullable compatibility fields are not evidence that the legacy model computes the 1.2 readout. For required/optional distinctions and exact serialization, use the machine-readable schema.

## Supported measurements and limits

Given a declared labeled dataset, its exclusions, preprocessing, class mapping, evaluation version, and operating point, the public labels support fixed-point false-positive rates, recall, accuracy, and confusion matrices. Confidence tiers support coverage and accuracy summaries. The public 1.2 API does not expose continuous scores, so it cannot support ROC/AUROC or arbitrary threshold sweeps.

Read the [published methodology](https://stylome.io/methodology) and [benchmark reports](https://stylome.io/transparency) with their source and register breakdowns. A calibration target does not establish the error rate of a new source. Treat a label as evidence for review, not proof of misconduct.