Status: PLANNED, not live. This page is the contract under design for the programmatic surface tracked as F-API-MCP-1. It is consistent with the machine-readable statement in aim.json: programmatic_access = planned, not yet available. Do not write a tool call against anything on this page. For early access, join the waitlist at xlnc.co or write matt@xlnc.co.

What the API will do#

Submit a response set against a calibrated scale. Receive a band location on the construct, the standard error stated at that location, and the calibration vintage of the instrument that produced the measure. API-first, not API-only: the human UI remains the reporting and audit layer.

Authentication model (planned)#

Anchor: `#authentication-model-planned`

• Keyed access. One API key per integration, issued per organization.
• Scoped keys. A key is scoped to the scales it may score against and to the certification tier it may request.
• Firewall statement. Keys are held server-side; no key ships in client HTML, matching the waitlist discipline on the marketing site.
• Nothing on this list is issued today. There is no key console, no auth endpoint, no bearer token. PLANNED.

Endpoints (planned)#

Anchor: `#endpoints-planned`

POST /v1/score
  Submit a response set. Returns a band location with the
  standard error stated at the value.

GET /v1/scales
  Machine-readable scale registry. Mirrors the human per-scale
  pages from one manifest so the two can never drift.

GET /v1/scales/{scale}/bands
  Per-band stated standard errors and certification tier,
  as of a stated calibration vintage.

GET /v1/measures/{id}
  Retrieve a prior measure with its vintage stamp.

MCP endpoint: planned alongside the HTTP surface, same payloads, for agent callers (the escrow-quality target use case in AGENTS.md). Not yet callable.

Request and response shapes (planned)#

Anchor: `#request-and-response-shapes-planned`

Request:

POST /v1/score
{
  "scale": "mhc",
  "responses": [
    {"item": "<item-id>", "score": 1},
    {"item": "<item-id>", "score": 0}
  ]
}

Response:

{
  "scale": "mhc",
  "band": "S11",
  "location_logit": "<stated at the value>",
  "se": "<stated at the value>",
  "calibration_vintage": "<date>",
  "tier": "Canonical"
}

Contract rules that will hold when the surface opens:

• Every response carries se and calibration_vintage. No bare scalar is a valid response.
• The tier field renders from the same lexicon as the site: Canonical, PILOT, or WATCH. A WATCH scale returns its tier with the result; decision-use prohibition for high-stakes calls is stated, not implied.
• Flagged states are data, not omissions: a below-floor or no-evidence condition returns a flag field, never a silently dropped row.

Error taxonomy (planned)#

Anchor: `#error-taxonomy-planned`

400  malformed_request      The payload does not parse or lacks required fields.
401  unknown_key            The key does not exist.
403  scope_exceeded         The key is not scoped to this scale or tier.
404  unknown_scale          The scale slug is not in the registry.
409  vintage_conflict       The requested vintage is not the instrument of record.
422  insufficient_evidence  The response set cannot support a measure at the
                            stated precision target; returned with the achieved
                            SE, not a bare failure.
429  rate_limited           Tier rate exceeded.

The error page is written in the same register as the success paths: plain, complete, and honest about failure shapes. An error taxonomy that hides a failure mode is the docs equivalent of dropping a below-floor row.

Changelog discipline (planned)#

Anchor: `#changelog-discipline-planned`

The API changelog will be versioned, dated, and tiered like claims: behavior changes are events with dates; anything that moves a number links to the science page or registration that earns it. The changelog does not exist yet because the API does not exist yet. PLANNED.

What exists today#

The measurement engine runs in the demo and in engagements; the human UI is the reporting layer. The headless surface described on this page is the roadmap. This page exists so the contract is inspectable before the endpoint opens, and so that aim.json, AGENTS.md, llms.txt, and this page all say the same thing: planned, not available.