# U+22A8

> Documentation for u22a8.ai — deterministic trait-scoring models. Define a standard of judgment from examples, train, and score content over a REST API and an MCP server.

## Docs

- [Authoring schemas](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/authoring-schemas.md): The published model.yaml and JSONL sample format for defining a model as files.
- [Fetch a URL and extract its text](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/extract/fetch-a-url-and-extract-its-text.md): Fetch a URL and return its extracted text — the same readable text the score endpoint scores when given a URL. Includes a content hash for deduplication.
- [REST API](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/introduction.md): The resource-shaped /v1 API: models, samples, training, and scoring over HTTP.
- [MCP server](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/mcp.md): Score, read, and author models from an AI client over the Model Context Protocol.
- [Batch upsert samples](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/batch-upsert-samples.md): Append samples to a model. Each sample's ``trait`` field is resolved by key or name. Scoring-kind only.
- [Batch upsert traits](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/batch-upsert-traits.md): Add or replace traits on a model, keyed by ``key`` (or derived from ``name`` when ``key`` is omitted). Scoring-kind only.
- [Create a model](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/create-a-model.md): Create a draft model. ``handle`` is required and must be in a namespace your key owns — there is no auto-minting. ``kind`` is reserved-now and only accepts ``scoring`` at launch.
- [Delete a model](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/delete-a-model.md): Archive a model: it moves to the ``archived`` state and stops serving on /v1. Samples and version history are retained. Idempotent — archiving an already-archived model returns 200. Permanent deletion is handled through account deletion, not this endpoint.
- [Delete one sample](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/delete-one-sample.md)
- [Delete one trait](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/delete-one-trait.md)
- [Discover traits](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/discover-traits.md): Derive intrinsic traits from the model's labelled samples and attach them. Draft-only. Returns 202 with a run id once enqueued; the model enters the ``busy`` state and returns to ``draft`` with the new traits visible on ``GET …/traits`` when discovery completes. A repeat of an in-flight or completed…
- [Get a model](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/get-a-model.md): Returns the model's structured detail as JSON. Set `Accept: text/markdown` to fetch the **model card** instead — the same markdown the MCP server exposes as the model's resource. Reading a model is never gated by its additional terms; the card is how a caller reviews those terms.
- [Get one trait](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/get-one-trait.md): One trait's metadata. Includes its ``kind`` and, for discovered (intrinsic) traits, the discovery diagnostics — ``discrimination``, ``explained_variance``, and ``anchor_sample_ids``. ``key`` matches by trait key or name.
- [List models](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/list-models.md): List models, ordered by handle. Returns a cursor-paginated page even when the result fits — clients should treat the shape as stable and opaque-cursor.
- [List samples](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/list-samples.md): Cursor-paginated sample listing. ``trait`` filters by key or name.
- [List traits](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/list-traits.md): Trait metadata with sample counts, descriptions, and polarity labels.
- [Synthesize samples](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/synthesize-samples.md): Generate labeled samples from the model's trait definitions and attach them tagged ``provenance='synthesized'`` (DR 037). Draft-only. Returns 202 + run id on enqueue; the model enters ``busy`` (``last_operation.kind='synthesize'``) and returns to ``draft`` with the new samples visible on ``GET /samp…
- [Train (or re-tune)](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/train-or-re-tune.md): Train the model or re-tune it. From ``draft``, a first call runs a full training pass and moves the model to ``ready``. From ``ready``, set ``reoptimize_params=true`` to run a fresh parameter search; without it the call is a no-op, since routine retraining on new samples happens automatically. Retur…
- [Update a model](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/update-a-model.md)
- [Update one trait](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/models/update-one-trait.md)
- [Compare two texts](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/scoring/compare-two-texts.md): Score two texts (`a` is baseline, `b` is candidate) and return the per-trait delta plus the overall improvement. URLs in `a` and `b` are auto-fetched.
- [Score content](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/scoring/score-content.md): Score content against the model's traits. URLs in `content` are auto-fetched and their extracted text is scored. Plain-text bodies (curl convenience: pipe a string or URL with no JSON wrapper) are accepted alongside JSON. Set `Accept: text/plain` for the bar-chart formatter.
- [Liveness check](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/system/liveness-check.md): DB connectivity check — same probe as the top-level ``/health``.
- [Activate a version (rollback / pin)](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/versions/activate-a-version-rollback-pin.md): Activate a version — point the model at the resolved version so it serves scores. Use it to roll back or pin. Non-destructive: new samples keep accumulating and automatic retraining keeps minting new versions regardless of which one is active.
- [Get a version](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/versions/get-a-version.md): Resolve a ``"vN"`` number or tag name to its full version, including the ``snapshot`` of trained parameters. The snapshot is large; for metadata only, use the list endpoint instead.
- [List versions](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/versions/list-versions.md): List a model's versions, newest first. Each version is a snapshot of the trained parameters. The cursor is the lowest ``version_no`` from the previous page.
- [Tag the active version](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/versions/tag-the-active-version.md): Pin ``{name}`` to the model's current active version. Re-using a tag moves the pointer. Tag names matching ``v\d+`` are rejected to keep the ``vN`` namespace unambiguous.
- [Untag a version](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/versions/untag-a-version.md)
- [Authentication](https://u22a8-police-sweep-2026-06-01.mintlify.app/authentication.md): How API keys, scopes, and namespaces control access.
- [Briefs](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/briefs.md): Supervision by description — articulate the standard and have labelled samples synthesized from it.
- [Composite](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/composite.md): One number summarizing a score card — the harmonic mean of the trait scores.
- [Confidence](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/confidence.md): How much to trust a score — high, moderate, or low — based on training-data density.
- [Discovery](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/discovery.md): Fit a model's trait axes from its samples instead of declaring them — producing intrinsic traits.
- [Model lifecycle](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/model-lifecycle.md): The states a model moves through — draft, busy, ready — and the operations that drive them.
- [Models](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/models.md): A learned geometry in embedding space that applies a standard of judgment to content.
- [Samples](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/samples.md): A labelled example — content paired with a label — and the form every kind of supervision resolves to.
- [Score card](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/score-card.md): The structure returned when content is scored: a score per trait, a composite, and the context to interpret them.
- [Score types](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/score-types.md): Each trait has one of four types, fixing its geometry, score range, and native metric.
- [Supervision](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/supervision.md): The guidance you give a model about what good means — samples, references, briefs, and feedback.
- [Tiers, breaks & headroom](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/tiers.md): How a trait score is graded: plain-language tiers, the trained breaks that define them, and the headroom to the next one.
- [Training](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/training.md): How supervision becomes a fixed scoring geometry — embedding math, no language model.
- [Traits](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/traits.md): An axis of judgment a model measures — one question, one score.
- [Versions](https://u22a8-police-sweep-2026-06-01.mintlify.app/concepts/versions.md): A snapshot of a model's trained parameters — named, activated, and rolled back to.
- [U+22A8 documentation](https://u22a8-police-sweep-2026-06-01.mintlify.app/index.md): Score content against trait-scoring models you define from examples — deterministic, with no language model at score time.
- [Quickstart](https://u22a8-police-sweep-2026-06-01.mintlify.app/quickstart.md): Get an API key and score your first text.

## OpenAPI Specs

- [openapi](https://u22a8-police-sweep-2026-06-01.mintlify.app/api-reference/openapi.json)

## Optional

- [Home](https://u22a8.ai)
- [Research](https://u22a8.ai/research)