Versioning

API Reference · v1

URL-versioned (/v1/, /v2/). Major versions supported for 18 months post-deprecation. Additive-only evolution within a major version: fields are added, never removed or semantically redefined. Beta constructs carry stability="beta" and a separate SLA.

Authentication

Bearer-token via Authorization header. Tokens are scoped per-environment (dev / staging / prod) and per-customer. Rotate via the dashboard.

Authorization: Bearer {your_api_key}

Endpoints

POST/v1/users/{id}/score

Score one or more constructs for a user.

Request

{
  "constructs": ["big5", "attachment", "emotion_granularity"],
  "include_state_trait_decomposition": true,
  "include_invariance": ["device", "language", "cohort_age"]
}

Response

// see overview page for the full reliability + decomposition + invariance shape

GET/v1/users/{id}/profile

Cached most-recent reading. Returns 304 if no new sessions.

POST/v1/users/{id}/feedback

Disagreement-feedback endpoint (Plan §11.5). Feeds factory supervision and conformal calibration-exclusion.

Request

{
  "construct_code": "neuroticism",
  "agreement": "disagree",
  "note": "I don't think I'm anxious — I think I'm careful",
  "observed_at": "2026-12-01T14:22:00Z"
}

Response

{ "ok": true }

POST/v1/users/{id}/probes

Delegated EMA — Enterprise reserved (Plan §11.6). Customer dispatches the probe through their own channel; Neumatics owns scoring.

Request

{
  "probe_type": "sam_valence_arousal",
  "response": { "valence": 5, "arousal": 7 },
  "observed_at": "2026-12-01T14:22:00Z",
  "channel_used": "partner_coaching_app",
  "content_version": "sam-v1"
}

Response

{ "accepted": true, "stored_layer": "L2" }

GET/v1/users/{id}/export

GDPR DSAR export. Returns full Layer 1/2/3 data + provenance.

DELETE/v1/users/{id}

Per-subject deletion. Cascades Firestore + BigQuery raw + aggregates + Agent Observability traces. Returns deletion receipt.

SDKs

Python and TypeScript SDKs ship at API GA (Phase 4). Generated from OpenAPI + hand-polished ergonomics. OpenAI-compatible function-call wrapper, Langchain / LlamaIndex connectors, and n8n / Zapier nodes land alongside.

Error envelope

{
  "error": {
    "code": "invariance_failed",
    "message": "Score withheld for cohort_neurodivergence; metric invariance not established.",
    "construct_code": "big5_neuroticism",
    "alternative": "tier_b_estimate"
  }
}